Markdown syntax

The majority of content within 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.

Frontmatter

A title is required frontmatter for most files. 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.

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

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

![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. Starlight does not provide a native way hide “Overview” or change the wording.

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

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, 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. Ping the person responsible for documentation architecture if your project doesn’t render mathjax properly.

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