Writing
Writing the home page and documents in Markdown
Write each document as one Markdown file. Put the document information at the top of the file and the body below it.
Your first document
Create content/public/guide.md and write the following.
---
name: Guide
label: Getting started with the project
group: Guide
order: 10
---
A guide for people who use the project for the first time.
## Installation
List what you need to prepare before installing.
## Usage
### First step
Describe the first task.
When you run dev, the document appears in the Guide group of the sidebar. The document address is /guide/.
The ## and ### headings appear in the page outline. The document title is displayed from name, so you do not need to repeat the same # heading in the body.
public holds documents to deploy, and private holds documents kept out of the public site. Other Markdown files outside these two folders are not added to the document list automatically.
Home page
content/README.md is the site home page (/). Write the title and introduction without frontmatter.
# Project notes
An introduction to the project and a guide to its documents.
[Get started](public/guide.md)
Selecting the site name goes to the home page. If there is no README, a guide to writing the home page appears. READMEs inside public and private are ordinary documents, so write frontmatter in them like in any other document.
Frontmatter
| Field | Use | Required |
|---|---|---|
name | Title shown in the body and the sidebar | Required, a non-empty string |
label | Document description shown under the title when it differs from name, and in the sidebar tooltip, search results and link previews | Required |
group | Sidebar group name or array of names | Required, a non-empty value |
order | Reading order within the same group | Optional, an integer of 0 or more |
parent | ID of the parent document in the same group | Optional |
created | Date the document was first written, shown under the title | Optional, YYYY-MM or YYYY-MM-DD |
revised | Date the document was last revised, shown under the title | Optional, same format, not earlier than created |
A new document does not need type. Existing document and blueprint values are still read and shown as the same kind of document.
You can use any language for titles and groups.
Dates
created: 2022-12
revised: 2026-10
The document above shows Created 2022-12, Revised 2026-10 in small gray text under the title. Pages in Korean label the dates 작성일 and 수정일, and pages in other languages use the English labels. Either date can be written alone.
Write a month as YYYY-MM or a day as YYYY-MM-DD. The date is shown as written. A different format, a day that does not exist or a revised date earlier than created is a build error.
A date written with the day also becomes the page’s <lastmod> in the sitemap. See Crawling.
Navigation groups
Documents with the same group are shown together. A smaller order is shown first. Documents without order are shown after the ordered ones, sorted by title.
group: [Projects, Research]
order: 10
The document above appears in the Research group inside Projects. The display order of groups is set with navigation in the site configuration.
Changing a group name or order does not change the document URL. To place child documents under a document, see the parent example in Navigation.
File names
The ID of a public document is the lowercase path relative to the public folder, without the extension. public/guide/setup.md is shown as /guide/setup/.
Private documents get a /private/ prefix. .mdx is also read as Markdown, and JSX is not executed.
Two files that resolve to the same ID cannot be used together. For example, Guide.md and guide.mdx conflict.
Do not use #, ?, %, *, :, \ or control characters in file names. The path segments ., .. and index.html are also not allowed.
The first path segments _fh and favicon.svg are for default assets, private is for private documents, and a language code from locales is for its translations. If you set url, robots.txt and sitemap.xml are reserved as well.
Sections and parts
## is a major section, and ### is a subheading under it. To group several related sections, put ::part[Title] before them.
::part[Getting started]
## Installation
Installation instructions.
## Usage
### First step
Running instructions.
A part divider marks a group of sections in the body and the outline. Headings are not numbered automatically. If you need numbers, write them in the heading yourself.
A ::part with no title or an empty title is a build error. The title is plain text without formatting and cannot take attributes.
After a ::part, there must be at least one Markdown ## section before the next ::part or the end of the document.
Links
To link to other documents and the home page from content/public/guide.md, write the following.
[Configuration](settings.md)
[Navigation configuration](settings.md#navigation)
[Home](../README.md)
Relative .md links are converted to site URLs, and the query and hash are kept. settings.md#navigation above links to /settings/#navigation.
A link to a README of an ordinary document goes to that document, and a link to content/README.md goes to the home page.
A link to a document that does not exist does not stop the build. The terminal shows a warning with the file and line number. The same conversion and warning apply to <a href="..."> in raw HTML.
A link to a local file of a type that is not deployed shows the same warning. For the types that are deployed, see Images.
Heading anchors are generated automatically from the headings. If the same heading repeats, -1 and -2 are appended.
A #hash that points to a heading that does not exist, in the same document or in another document, shows the same kind of warning with the file and line number. Links to headings on the home page are not checked. Supported since 0.24.0.
An id written in raw HTML, such as <a id="01"></a> inside a heading, is also a target, so a link can use a stable number instead of the heading text. Since 0.29.1.
A raw <a id="ssd-001"></a> at the start of a table cell makes that row a target. Arriving there highlights the row for a few seconds, and the cell stays on one line. A link whose text is an identifier with a hyphen and a number, such as SSD-001 or PROJ-12, stays on one line instead of breaking after the hyphen, and so does a link that starts with an image, such as an icon before a label. Since 0.31.0.
Navigating to a heading inside Details expands the collapsed content.
In public documents and the home page, do not link to private files or /private/ paths.
A link whose text is a configured prefix and a number, such as [Q3](questions.md#q3), is shown as a chip. See Reference chips.
A link in the body opens in a new tab, except a #hash link to the same page. The linkTarget setting in Site changes this. Since 0.32.0.
Flowcharts
Set the language of the code block to mermaid.
```mermaid
flowchart LR
Draft[Write] --> Review[Review]
Review --> Publish[Publish]
```
flowchart LR
Draft[Write] --> Review[Review]
Review --> Publish[Publish]A label is not wrapped automatically; its box grows to fit the text. Write <br> where a label should break.
For examples of diagrams for sequences, states, relationships and folder structures, see Diagrams.
Code notation
Write a language name on a code block to highlight its syntax. line-numbers shows line numbers, and [file name] shows a file title.
```ts line-numbers [example.ts]
const title = "Project notes";
const count = 3;
```
const title = "Project notes";
const count = 3;| Notation | Result |
|---|---|
// [!code highlight] or code block meta {2,4-6} | Highlights the lines |
// [!code error] and // [!code warning] | Marks error and warning lines |
// [!code ++] and // [!code --] | Marks added and removed lines |
// [!code word:title] | Highlights a word in that line |
Meta line-numbers | Line numbers |
Meta bad and good | Distinguishes the backgrounds of wrong and correct examples |
Meta [file name] | File name above the code |
Notation comments are hidden in the output. Use the comment syntax of each language.
Code snippets
If you keep example code in separate files, you can import it with <<<.
<<< ./example/response.ts
<<< ./example/response.ts#contract line-numbers [response.ts]
The path is relative to the current Markdown file. The file must be inside the content root. Public documents cannot import private files.
Adding #contract shows only the part of the file between // #region contract and // #endregion contract. An unnamed // #endregion closes the innermost open region.
Write a region marker as #region after a comment symbol, as in // #region contract, /* #region contract */ or <!-- #region contract -->. In files with the following extensions, you can also use that language’s notation.
| Extension | Additional marker |
|---|---|
.py, .yml, .yaml, .sh, .bash, .zsh, .coffee, .cs, .ps1 | # region contract, # #region contract |
.c, .h, .cc, .cpp, .cxx, .hh, .hpp, .hxx | #pragma region contract |
In files with other extensions, lines written with a space such as # region or ## region remain as body text, not markers.
To write the end marker, replace region with endregion.
Region marker lines and the common indentation are removed. Specifying a region that does not exist, or a region that is not closed by the end of the file, is a build error.
The language is determined by the file extension. After the path you can use the same meta as a code block. In dev, changes to imported files are also reflected.
Content features
You can use tables, lists, task lists, links, inline code and ordinary Markdown formatting.
Strikethrough needs two tildes on each side, as in ~~done~~. A single ~ stays as written, so a range such as 10~11 is not struck through.
For image and attachment paths, see Images, and for emphasis of status phrases in the body, see Status badges.
Hex color values of 3, 4, 6 or 8 digits written as inline code, such as #e80030, are shown with a color swatch.
You can also use raw HTML, but it does not automatically fetch CSS and JavaScript from other sites.
Heading anchors are also created for <h2> and <h3> in raw HTML, and they appear in the outline. Raw HTML tables are also put in the same horizontal scroll box as Markdown tables.
Raw HTML can also be an interactive figure with steps, a slider or a runnable code block. See Figures.
A table with a header row and at least two body rows sorts by its column headers. Pointing at a header shows an arrow at its right edge; the first click sorts ascending, the second descending and the third restores the written order, and the arrow turns as the direction changes.
Numbers and dates in the text sort by value, empty cells and - stay at the end, and the sorted column is exposed to assistive technology as aria-sort. Without JavaScript the table keeps its written order.
A table with merged cells or a link in a header keeps its written order. Supported since 0.27.0.
Block components
Use Note to keep supplementary explanations visible, and Details to let readers expand them when needed.
:::note[Before you start]
Node.js 22.12.0 or later is required.
:::
:::details[More information]
Use one configuration file per project.
:::
A title and a body are required. Adding {open} to Details makes it open from the start.
For examples, nesting rules and error rules, see Parts.