Point the site at the .md files already in your repository and they render at least as well as on GitHub: the
same syntax, the same heading anchors, nothing to rewrite. This page is a plain .md file and shows each feature as
its source, then the result.
It works on every page that renders markdown: local docs pages (.md and .mdx), folders mounted with
externalDocs, blog posts, and your own pages. Nothing to install or configure; each extra can be switched
off.
**Bold**, *italic*, ***both***, ~~strikethrough~~, `inline code`, H<sub>2</sub>O, x<sup>2</sup>,<kbd>Ctrl</kbd> + <kbd>K</kbd>, and emoji shortcodes :tada: :rocket: :+1:.
Bare links become links: www.example.com, https://astro.build/ and docs@example.com.Bold, italic, both, strikethrough, inline code, H2O, x2,
Ctrl + K, and emoji shortcodes 🎉 🚀 👍.
Bare links become links: www.example.com, https://astro.build/ and docs@example.com.
Emoji use GitHub’s names (the gemoji list); an unknown :name: stays as typed,
and code is never touched. Quotes and ... become typographic; -- stays as typed, as on GitHub, so CLI flags in
prose survive.
Headings and anchors
Section titled “Headings and anchors”Every heading gets an id made the way GitHub makes it (lowercase, spaces to dashes, punctuation dropped, -1,
-2… for repeats), so a #fragment link copied from GitHub lands on the same heading here. Hover a heading for its
link. This section is #headings-and-anchors, as on GitHub.
Lists and task lists
Section titled “Lists and task lists”1. First2. Second - nested - [x] done, a task inside a list- [x] Write the docs- [ ] Ship it - [ ] Announce it- First
- Second
- nested
- done, a task inside a list
- Write the docs
- Ship it
- Announce it
Task lists render as checkboxes that cannot be clicked, as on GitHub outside issues.
Tables
Section titled “Tables”Column alignment with :--, :-: and --:. A table wider than the column scrolls in its own box (with a tab stop,
so the keyboard can scroll it too), never the page.
| Left | Centre | Right || :--- | :----: | ----: || `a` | b | 1 || long cell text | ✓ | 1,024 || Left | Centre | Right |
|---|---|---|
a |
b | 1 |
| long cell text | ✓ | 1,024 |
| Option | Type | Default | Applies to | Since | Description |
|---|---|---|---|---|---|
markdown.alerts |
boolean |
true |
every markdown page | 0.2.0 | GitHub alert blockquotes become callouts with an icon and a title. |
markdown.mermaid |
boolean |
true |
every markdown page | 0.2.0 | Mermaid code blocks are drawn as diagrams in the browser, lazily. |
markdown.math |
boolean |
true |
every markdown page | 0.2.0 | Dollar-sign math and math code blocks are typeset with KaTeX at build time. |
Alerts
Section titled “Alerts”GitHub’s five alerts. The marker goes alone on the first line of a blockquote.
> [!NOTE]> Useful information that users should know, even when skimming content.
> [!TIP]> Helpful advice for doing things better or more easily.
> [!IMPORTANT]> Key information users need to know to achieve their goal.
> [!WARNING]> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]> Advises about risks or negative outcomes of certain actions.An alert can hold anything a blockquote can: paragraphs, lists, code. A blockquote without a marker stays a blockquote:
Just a quote. Markdown still works in it.
In docs pages Starlight’s own :::note / :::tip / :::caution / :::danger asides work too; alerts are the
syntax that also renders on GitHub.
Footnotes
Section titled “Footnotes”Footnotes are numbered in order of use[^first], can be referenced again[^first], and can holdformatting[^long].
[^first]: The first footnote.[^long]: A longer one, with `code` and a [link](https://github.com/).Footnotes are numbered in order of use1, can be referenced again1, and can hold formatting2.
They are listed at the end of the page under “Footnotes”, each with a link back to where it was used.
Collapsed sections
Section titled “Collapsed sections”<details><summary>Click to expand</summary>
Markdown works inside, after a blank line: **bold**, lists, code.
```jsconsole.log('hidden until opened');```
</details>Click to expand
Markdown works inside, after a blank line: bold, lists, code.
console.log('hidden until opened');Images
Section titled “Images”
Relative paths are resolved from the markdown file (and optimised at build time), so images next to your README
keep working when the folder is mounted with externalDocs.
Typeset with KaTeX at build time: no JavaScript in the page, and KaTeX’s stylesheet is linked only from pages that contain math.
Inline: $e^{i\pi} + 1 = 0$, and the area of a circle is $A = \pi r^2$.
$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}$$
```math\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t}\end{aligned}```Inline: , and the area of a circle is .
Wide formulas scroll sideways in their own box. A typo in a formula shows the source in red instead of failing the build. Screen readers get MathML.
Code blocks
Section titled “Code blocks”Code blocks use Expressive Code with every language Shiki knows; an unknown language renders as plain text with a build warning, never an error. Each block has a copy button, and blocks whose lines do not fit get a wrap lines toggle (try this page on a phone).
Titles and frames
Section titled “Titles and frames”```js title="src/greet.js"export const greet = (name) => `Hello, ${name}!`;```
```ts// src/config.tsexport const retries = 3;```export const greet = (name) => `Hello, ${name}!`;export const retries = 3;A first-line comment that looks like a file name becomes the title, as above.
Terminals and prompts
Section titled “Terminals and prompts”Shell languages (bash, sh, zsh, shell, powershell) get a terminal frame. A $ prompt cannot be selected
and is not copied; when a block mixes commands and output, the copy button copies only the commands.
```bash# Comments are not copied eithernpm create astro@latest -- --template minimal```
```sh$ npx astro-project-site@beta init my-site```
```console$ npm install astro-project-siteadded 312 packages in 9s$ npx astro-project-site@beta init my-site --name "My Lib"Created my-site/ (14 files)```# Comments are not copied eithernpm create astro@latest -- --template minimal$ npx astro-project-site@beta init my-site$ npm install astro-project-siteadded 312 packages in 9s$ npx astro-project-site@beta init my-site --name "My Lib"Created my-site/ (14 files)```diff- const answer = 41;+ const answer = 42; console.log(answer);```
```diff lang="ts" function total(items: Item[]) {- return items.reduce((a, b) => a + b.price, 0);+ return items.reduce((sum, item) => sum + item.price * item.quantity, 0); }```
```js ins={2} del={1} "price"const total = items.length * price;const total = items.reduce((sum, item) => sum + item.price, 0);```const answer = 41;const answer = 42;console.log(answer);function total(items: Item[]) { return items.reduce((a, b) => a + b.price, 0); return items.reduce((sum, item) => sum + item.price * item.quantity, 0);}const total = items.length * price;const total = items.reduce((sum, item) => sum + item.price, 0);A plain diff block colours + and - lines; diff lang="ts" also highlights the code. The copy button copies
the code without the +/- markers.
Highlighting, line numbers, collapsing, wrapping
Section titled “Highlighting, line numbers, collapsing, wrapping”```astro {2} "Astro.props" showLineNumbers collapse={7-9}---const { title } = Astro.props;---<article> <h2>{title}</h2> <slot /> <footer> <a href="#top">Back to top</a> </footer></article>```
```txt wrapA long line of plain text that wraps instead of scrolling, because the block asks for it with the wrap option in its meta string.```---const { title } = Astro.props;---<article> <h2>{title}</h2> <slot />3 collapsed lines
<footer> <a href="#top">Back to top</a> </footer></article>A long line of plain text that wraps instead of scrolling, because the block asks for it with the wrap option in its meta string.// A long line without `wrap`: on a narrow screen the block scrolls, and a "Wrap lines" button appears next to the copy button.const url = new URL('/docs/guides/markdown/#code-blocks', 'https://astro-project-site.pascaripavel.workers.dev').toString();Meta syntax
Section titled “Meta syntax”What goes after the language on the opening fence:
| Meta | Effect |
|---|---|
title="file.js" |
Title in the frame (a first-line // file.js comment does the same) |
frame="terminal", frame="code", frame="none" |
Choose the frame instead of the automatic one |
{2}, {1,4-6} |
Highlight lines |
ins={2}, del={3-4} |
Mark lines as inserted or deleted |
"word", /regex/ |
Highlight text; ins="…", del="…" for inserted/deleted text |
lang="ts" on a diff block |
Diff markers plus highlighting for that language |
showLineNumbers, startLineNumber=10 |
Line numbers (off by default, as on GitHub) |
collapse={1-5} |
Collapse lines behind a “N collapsed lines” toggle |
wrap |
Wrap long lines instead of scrolling |
Languages
Section titled “Languages”Every Shiki language works. Common ones, by the names GitHub uses:
| Kind | Languages |
|---|---|
| Shell | bash, sh, zsh, shell, powershell/ps1, console/shell-session (prompts and output), bat |
| Data and config | json, jsonc, json5, yaml, toml, ini, xml, csv, env/dotenv, properties |
| Web | js, ts, jsx, tsx, astro, html, css, scss, vue, svelte, graphql, http |
| Docs | md, mdx, diff, text/txt/plaintext, math (typeset), mermaid (drawn) |
| Systems and backend | python, go, rust, java, kotlin, c, cpp, csharp, ruby, php, swift, sql |
| Ops | dockerfile, nginx, terraform/hcl, make, proto |
Plain text: no highlighting, still a copy button.GET /docs/ HTTP/2Accept: text/htmldef fib(n: int) -> int: return n if n < 2 else fib(n - 1) + fib(n - 2)fn main() { println!("Hello from {}", env!("CARGO_PKG_NAME"));}Mermaid diagrams
Section titled “Mermaid diagrams”A mermaid code block becomes a diagram. Mermaid loads only on pages that have one, only when a diagram scrolls
near, and draws in the site’s colours (switch the theme to see it redraw). Wide diagrams keep a readable size and
scroll sideways. The source stays under each diagram, and is what shows if a diagram cannot be drawn (or before
JavaScript runs).
Mermaid is an optional dependency, because it is large (about 127 MB in node_modules). Install it in your site to
draw diagrams:
npm i mermaidproject-site init adds it for you when your repository’s markdown already has a mermaid block. Without it,
diagrams show their source with a note saying how to draw them, and the build prints one warning naming the first
file that has one; set markdown: { mermaid: false } to silence that.
```mermaidflowchart LR md[Your .md files] --> site[astro-project-site] site --> docs[Docs] & blog[Blog] & llms[llms.txt]```flowchart LR md[Your .md files] --> site[astro-project-site] site --> docs[Docs] & blog[Blog] & llms[llms.txt]
sequenceDiagram autonumber participant B as Browser participant S as Site B->>S: GET /docs/guides/markdown/ S-->>B: HTML (diagram source inside) B->>B: scrolls near a diagram B->>S: GET mermaid chunk S-->>B: JavaScript Note over B: draws the SVG in the site's colours
classDiagram
class Page {
+string title
+render() HTML
}
class DocsPage
class BlogPost {
+Date date
}
Page <|-- DocsPage
Page <|-- BlogPoststateDiagram-v2 [*] --> Source Source --> Pending: scrolls near Pending --> Drawn: parsed Pending --> Error: invalid Drawn --> Drawn: theme switch Error --> [*]
erDiagram
PROJECT ||--o{ PAGE : has
PAGE ||--o{ HEADING : contains
PAGE }o--o{ TAG : "tagged with"gantt
title Release plan
dateFormat YYYY-MM-DD
axisFormat %b %d
tickInterval 1week
section Docs
Write guides :done, d1, 2026-01-05, 7d
Review :active, d2, after d1, 4d
section Site
Markdown parity :crit, s1, 2026-01-08, 9d
Launch :milestone, after s1, 0dpie title Where the bytes go "HTML" : 42 "CSS" : 18 "JavaScript" : 25 "Fonts" : 15
mindmap
root((Markdown))
GitHub syntax
Alerts
Task lists
Footnotes
Extras
Math
Diagrams
Emojitimeline title astro-project-site 2025 : First landing page 2026 : Docs mounting : Markdown parity Next : Blog
gitGraph commit branch feature checkout feature commit commit checkout main merge feature commit
A wide diagram:
flowchart LR a[Write markdown] --> b[Commit] --> c[Open a pull request] --> d[CI builds the site] --> e[Preview deploy] --> f[Review] --> g[Merge] --> h[Production deploy] --> i[Readers]
A diagram with a mistake shows its source and a note instead:
flowchart LR a --> this is not mermaid
Diagrams use Mermaid’s classic dagre layout. Its optional ELK engine is EPL-licensed and not bundled, so a
diagram that asks for layout: elk shows its source instead.
Give a diagram an accessible title and description with Mermaid’s accTitle: and accDescr: lines; without them it
is announced by its type, and its source is available under “Diagram source”.
Raw HTML
Section titled “Raw HTML”HTML in markdown is passed through as written, as GitHub does for the tags it allows (<details>, <kbd>,
<sub>, <sup>, <picture>, <br>, alignment attributes, comments…). Unlike GitHub, nothing is stripped: the
markdown is your own repository’s, so <script>, <style>, <iframe> and style="" work too. Do not render
markdown you do not trust with this site.
Options
Section titled “Options”Everything above is on by default. Each extra can be switched off with the markdown option:
projectSite({ // ... markdown: { alerts: true, // > [!NOTE] callouts emoji: true, // :tada: shortcodes math: true, // $…$, $$…$$, ```math (KaTeX) mermaid: true, // ```mermaid diagrams headingLinks: true, // anchor links on headings outside the docs (Starlight adds its own in the docs) codeWrapToggle: true, // "Wrap lines" button on code blocks that overflow },});Code block settings go to Starlight’s expressiveCode
option, starlight: { expressiveCode: { … } }: its plugins are added after the built-in ones, and its
defaultProps and shiki.langAlias win (defaultProps: { showLineNumbers: true } numbers every block).