Skip to content
GitHub

Markdown syntax

Starlight supports the full range of Markdown syntax in .md files as well as frontmatter YAML to define metadata such as a title and description.

Please be sure to check the MDX docs or Markdoc docs if using those file formats, as Markdown support and usage can differ.

Frontmatter

The title is a required field and if you create an .md or .mdx file without it in the content folder, the site will yell at you. Please check the full list of frontmatter configuration for more fun options.

---
title: Remember to set this
---

Inline styles

Text can be bold, italic, or strikethrough.

Text can be **bold**, _italic_, or ~~strikethrough~~.

You can link to another page.

You can [link to another page](/getting-started/).

You can highlight inline code with backticks.

You can highlight `inline code` with backticks.

Images

Images in Starlight use Astro’s built-in optimized asset support.

Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology.

An illustration of Ernie perched atop a laptop next to the Interledger Logo

![An illustration of Ernie perched atop a laptop next to the Interledger Logo](/img/image.png)

We standardise our image location for every project to be in the /public/img folder. Start with /img/ when calling an image.

/// src/content/docs/introduction/architecture.md
![Architecture diagram](/img/rafiki-architecture.png)

You may want to further organise the img folder with subfolders if the project has a lot of images.

Headings

Starlight is configured to automatically use your page title as a top-level heading and will include an “Overview” heading at top of each page’s table of contents. If you need to modify this behavior for whatever reason, please consult the person responsible for documentation architecture.

Using headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page:

---
title: My page of content
description: How to use Starlight's built-in anchor links
---
## Introduction
I can link to [my conclusion](#conclusion) lower on the same page.
## Conclusion
`https://my-site.com/page1/#introduction` navigates directly to my Introduction.

Level 2 (<h2>) and Level 3 (<h3>) headings will automatically appear in the page table of contents. Starlight allows you to override this behavior.

Asides

Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content.

Starlight provides a custom Markdown syntax for rendering asides. Aside blocks are indicated using a pair of triple colons ::: to wrap your content, and can be of type note, tip, caution or danger.

You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content.

Note aside

:::note
Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command:
```sh
npm create astro@latest -- --template starlight
```
:::

Custom aside titles

You can specify a custom title for the aside in square brackets following the aside type, e.g. :::tip[Did you know?].

:::tip[Did you know?]
Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/).
:::

More aside types

Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up. If you find yourself using these a lot, it may also be a sign that the thing you are documenting could benefit from being redesigned.

:::caution
If you are not sure you want an awesome docs site, think twice before using [Starlight](../../).
:::
:::danger
Your users may be more productive and find your product easier to use thanks to helpful Starlight features.
- Clear navigation
- User-configurable colour theme
- [i18n support](/guides/i18n)
:::

Blockquotes

This is a blockquote, which is commonly used when quoting another person or document.

Blockquotes are indicated by a > at the start of each line.

> This is a blockquote, which is commonly used when quoting another person or document.
>
> Blockquotes are indicated by a `>` at the start of each line.

Code blocks

A code block is indicated by a block with three backticks ``` at the start and end.

This is a simple rendered code block.
Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Hovering over a Starlight code block will display a copy button.

Syntax highlighting

You can indicate the programming language to use if you want to use syntax highlighting. Astro uses the Shiki highlighter, so check their documentation if you aren’t sure if your language is supported.

The following example shows Javascript syntax highlighting.

var fun = function lang(l) {
dateformat.i18n = require("./lang/" + l);
return true;
};

Apply syntax highlighting by adding the language directly after the opening backticks, with no space in between.

```js
var fun = function lang(l) {
dateformat.i18n = require("./lang/" + l);
return true;
};
```

Expressive code

Starlight uses Expressive Code to extend formatting possibilities for code blocks. These include text markers, titles, and frames.

Titles

When we first deployed Starlight, it didn’t support adding titles to code blocks. This is why we have the in-house CodeBlock component.

Example code block with a title

This code block has a title! HJ made the component. Isn't she neat?

As of November 2023, Starlight now supports adding titles to code blocks; however, the title is styled to appear in a tab. Also, to use the Starlight title, you must specify a language.

Starlight default title style
I mean, at least it works by default now, right?
```tex title="Starlight default title style"
I mean, at least it works by default now, right?
```

Code blocks will be rendered as a terminal window if their language identifier is bash, shellscript, shell, sh, or zsh. Titles are styled differently in this context.

For example:

This uses bash
See what it looks like?

Frames

A terminal window is a type of frame. Expressive Code allows you to override whichever default frame a code block uses.

Note that using none will hide a code block’s title.

Other common Markdown features

Starlight supports all other Markdown authoring syntax, such as lists and tables. See the Markdown Cheat Sheet from The Markdown Guide for a quick overview of all the Markdown syntax elements.

Tables

SyntaxDescription
HeaderTitle
ParagraphText
| Syntax | Description |
| --------- | ----------- |
| Header | Title |
| Paragraph | Text |

Lists

Unordered List

  • Dinosaurs are cool
  • Cats are awesome
  • Sleep more, it’s good for your brain
- Dinosaurs are cool
- Cats are awesome
- Sleep more, it's good for your brain

Ordered List

  1. Wake up
  2. Brew coffee
  3. Do work
1. Wake up
2. Brew coffee
3. Do work

Task List

  • Write the press release
  • Update the website
  • Contact the media
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

Footnotes

Here’s a sentence with a footnote. 1

Here's a sentence with a footnote. [^1]

The footnote will show up at the end of the content, down the bottom of the page. It is by default formatted as an ordered list, under a screen-reader only section <h2> header called “Footnotes”.

Advanced Markdown and MDX configuration

Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding remarkPlugins or rehypePlugins in your Astro config file. See “Configuring Markdown and MDX” in the Astro docs to learn more.

Mermaid diagrams

Mathjax

$currencyAmount = \frac{value}{10^{assetScale}}$

Footnotes

  1. This is the footnote.