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](/).

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](/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.

Automatic heading anchor links

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.

Example

Note

Starlight is a documentation website toolkit built with Astro. You can get started with this command:

npm create astro@latest -- --template starlight

:::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 titles

You can specify a custom title for the aside in square brackets following the aside type. For example:

:::tip[Did you know?]

Guess what?!

Astro helps you build faster websites with “Islands Architecture”.

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

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.

Note

As of November 29, 2023, this button will not appear when using the in-house ChunkedSnippet component. We’re tracking the issue in https://github.com/interledger/open-payments/issues/384.

Syntax highlighting

You can indicate the programming language to use if you want to use syntax highlighting. Astro uses Shiki, 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?

```js 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

Syntax	Description
Header	Title
Paragraph	Text

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

Note

If the style of a Markdown table doesn’t work for what you’re doing, you can create an HTML table.

Lists

Unordered List

Use when the order of the items in the list isn’t important.

• 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

Use when the order of the items in the list is important, such as for steps that must be followed in a specific order.

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. ¹

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

Danger

We no longer support mermaid diagrams using the markdown syntax. Instead, please use our custom Mermaid component.

Mathjax

Caution

This component requires an extra dependency on remark-math and rehype-mathjax and thus is not enabled by default on all projects. Please ping the person responsible for documentation architecture if your project doesn’t render mathjax properly.

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

Footnotes

1. This is the footnote. ↩