Markdown syntax
Most content in the documentation projects are written in Markdown. This page touches on some high-level Markdown topics. For more information on Markdown syntax, see:
- https://starlight.astro.build/guides/authoring-content/
- https://www.markdownguide.org/basic-syntax/
- https://www.markdownguide.org/extended-syntax/
Frontmatter YAML is used to define metadata such as a title and description.
Escape character
Section titled “Escape character”Escape a character by adding a backslash before the character.
For example, to show {client_domain/jwks.json} in plain text (as shown here), without Starlight giving you an error, you’d need to format it like this:
\{client_domain/jwks.json}
Frontmatter
Section titled “Frontmatter”Most files require a title in their frontmatter.
---title: Remember to set this---One scenario in which a title is not required is when the file is a partial.
Check the full list of frontmatter configuration for more fun options.
Images
Section titled “Images”Images in Starlight use Astro’s built-in optimized asset support.
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
You may want to further organise the img folder with subfolders if the project has a lot of images.
Headings
Section titled “Headings”Starlight automatically uses your page title as a top-level heading and includes an “Overview” heading at top of each page’s table of contents. Starlight doesn’t provide a native way hide “Overview” or change the wording. However, we do have the RemoveOverview component.
Automatic heading anchor links
Section titled “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 automatically appear in a page’s table of contents. Starlight allows you to override this behavior.
Advanced Markdown and MDX configuration
Section titled “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
Section titled “Mermaid diagrams”Use our custom Mermaid component to add Mermaid diagrams to the docs.
Mathjax
Section titled “Mathjax”$currencyAmount = \frac{value}{10^{assetScale}}$