Writing Content

Every page is a .mdx file. MDX is a superset of Markdown that can import and render React components, but all standard Markdown syntax works just fine when you don’t need components. Plain .md files aren’t supported. folio.md fails the build with an error when it finds any in the content directory.

Markdown features

folio.md enables GitHub Flavored Markdown (opens in new tab) via remark-gfm, which adds:

• Tables: see Configuration for examples
• Strikethrough: ~~text~~
• Task lists: - [x] done / - [ ] todo
• Autolinks: bare URLs become links automatically

Mermaid diagrams

Wrap a Mermaid diagram in a fenced code block tagged mermaid. folio.md renders it to SVG at build time and ships no JavaScript to the browser. When you enable both light and dark modes, folio.md renders each diagram twice, once per theme, and uses CSS to show the correct version. Only the active theme’s SVG is visible at any time.

Each diagram also gets an Enlarge button. Clicking it opens the diagram in a full-screen modal where you can pan and zoom using a mouse or pointer gestures.

```mermaid
flowchart LR
    A[Write MDX] --> B[Build] --> C[Static SVG]
```

Syntax-highlighted code blocks

Tag a fenced block with a language identifier and Shiki highlights it at build time. folio.md injects a header bar with the language name and a copy button into every code block.

To show a filename in the header bar, add title="filename" to the opening fence:

```ts title="src/main.ts"
console.log("hello");
```

Callout blocks

Use :::type containers to draw attention to important content. Four types are available: note, tip, warning, and danger.

:::tip
This is a tip.
:::

Callout blocks support all standard Markdown inside them, including inline code, links, and lists.

File naming and sidebar order

folio.md strips numeric prefixes from file names to build the URL slug but uses them to sort sidebar entries. Without a numeric prefix, entries sort alphabetically.

Nested folders

Folders inside the content directory become collapsible sidebar sections. folio.md derives the section label from the folder name, stripping numeric prefixes. Nesting pages more than 2 folders deep emits a build warning.

Section metadata with _section.mdx

Place a _section.mdx file inside a folder to override the section’s sidebar title and icon:

docs/
  guide/
    _section.mdx
    getting-started.mdx
    configuration.mdx

---
title: Guide
icon: Book
---

_section.mdx never renders as a page. It works at one or two levels of nesting. Placing it three or more levels deep triggers a build warning and folio.md ignores it.

Every top-level folder must contain an index.mdx file, or the build fails with a clear error. That index.mdx is always sorted first in the section regardless of any numeric prefix.

Page settings

At the top of every .mdx file, between --- delimiters, you configure the page. The title field is the only required setting:

---
title: My Page
description: A short summary for search engines and social previews.
author: Alice
icon: Rocket
---

folio.md uses title as the page heading, browser tab title, and search result title. Set description to control the search snippet and social card preview. See Page Settings for the full list of options.