The title is a required field and if you create an
.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.
Text can be bold, italic, or
You can link to another page.
You can highlight
inline code with backticks.
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.
We standardise our image location for every project to be in the
/public/img folder. Start with
/img/ when calling an image.
You may want to further organise the img folder with subfolders if the project has a lot of images.
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:
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 (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
You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content.
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?].
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.
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.
A code block is indicated by a block with three backticks
``` at the start and end.
Hovering over a Starlight code block will display a copy button.
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.
Apply syntax highlighting by adding the language directly after the opening backticks, with no space in between.
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
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.
Code blocks will be rendered as a terminal window if their language identifier is
zsh. Titles are styled differently in this context.
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.
- Dinosaurs are cool
- Cats are awesome
- Sleep more, it’s good for your brain
- Wake up
- Brew coffee
- Do work
- Write the press release
- Update the website
- Contact the media
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
rehypePlugins in your Astro config file. See “Configuring Markdown and MDX” in the Astro docs to learn more.
This is the footnote. ↩