#Markdown & MDX
Author content in Markdown or MDX - GFM, admonitions, math, diagrams, and components.
Content pages can be authored in Markdown (.md) or MDX (.mdx) - Markdown
with embedded JSX components. Both compile to static HTML at build time.
#Frontmatter
Each content page starts with YAML frontmatter:
---
title: My Page
order: 2
sidebar: guides
keywords: [setup, install]
---
# Content starts here| Key | Purpose |
|---|---|
title |
Page title (used in the sidebar and <title>) |
order |
Sort order within a directory (default 999) |
sidebar |
Sidebar section override, or [...] JSON for a fully custom sidebar |
keywords |
Explicit search keywords for the search index |
Frontmatter is a small YAML subset: scalars, quoted strings (with the usual
\n, \t, \uXXXX escapes), [a, b] lists, nested maps, and block scalars
(description: | keeps line breaks, description: > folds them; |-/>-
strip the trailing newline). A quoted string can continue on the next lines;
the break folds to a space. Anchors, aliases and tags are not supported. A
+++ (TOML) block, or a --- block that is never closed, is not read; Krate
warns with the line instead of rendering it as text.
Frontmatter that is closed but malformed fails the build with the file, line and
column, instead of shipping a wrong value: a quoted value that is never closed
(title: "bad), text after a closing quote (title: "a" b), a [ or { that
is never closed, or a line that is not key: value. Quote a value that contains
: or #; title: "Hello: World" is fine.
#Markdown features
Markdown is parsed by goldmark, a CommonMark implementation (the full CommonMark 0.31 example suite is part of Krate's tests), with these extensions:
- GFM - tables, task lists, strikethrough, and
www./URL/email autolinks - Heading anchors - every heading gets an
idfor deep-linking and the TOC. Ids are built from the heading's visible text (Unicode letters are kept, so## Ünïcödéand CJK headings work) and repeated headings get-1,-2suffixes. - Raw HTML - HTML in a document is passed through as CommonMark specifies
(
<kbd>,<details>,<span>, ...). Markdown content is trusted project content;javascript:/data:link and image destinations are still removed. - Code fence info -
```ts title="app.ts" {1,3-5}sets the language plus atitle(shown in the code block header) and highlight line ranges (emitted asdata-highlight-linesfor your theme).~~~fences work too. - GFM alerts -
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING]and> [!CAUTION]render like the:::noteadmonitions. - Definition lists - a term line followed by
: definitionlines - Footnotes -
[^1]references with[^1]: textdefinitions - Emoji shortcodes -
:rocket:-> rocket emoji (outside code spans) - Admonitions
This is a note. Admonitions are enabled with admonitions: true in the
markdown config.
This is a warning callout.
Admonition types include note, tip, warning, and danger.
- Syntax highlighting - fenced code blocks are highlighted at build time:
export default function Hello() {
return <h1>Hello, MDX!</h1>;
}-
Math - with
math: true,$inline$and$$display$$spans are wrapped in.krate-mathelements. In the docs plugin, KaTeX is loaded from a CDN and auto-renders them; elsewhere the spans are left for your own renderer/CSS. Code spans/blocks are never touched:The identity $e^{i\pi} + 1 = 0$ is famous. $$\int_0^1 x\,dx = \tfrac{1}{2}$$
#Diagrams
With mermaid: true, fenced mermaid blocks render as diagrams:
graph TD A[Source TSX] --> B[Go compiler] B --> C[Static HTML] B --> D[Hydration JS]
#Component directives
Import a component, then wrap content in it with a :::component directive -
the body is rendered as Markdown and passed to the component as HTML:
import { Card, Steps } from '@krate/components';
:::component Card title="Getting started"
Krate **compiles** Markdown into your components, with full Markdown inside.
:::Directives are expanded to real component JSX at build time, so they appear in
the output as static HTML with no client runtime. This works for any imported
component (:::component Steps, :::component Aside type="tip", ...).
#Built-in directives
Four container directives lower to @krate/components without any import (the
docs plugin auto-imports them):
:::card Title...:::- wraps the body in aCard.:::stepswith nested::step Titleitems - aStepslist.:::tabswith nested::tab Labelitems - aTabspanel.:::code-groupwith fenced code blocks - one tab per language.
:::steps
::step Install
Run `npm install`.
::step Build
Run `krate build`.
:::The Tabs (Tabs.List/Tabs.Trigger/Tabs.Content), Steps (Steps.Step), Card,
and Code components are imported automatically when their directive is used.
#MDX
MDX lets you embed JSX directly in your content. Beyond block-level components, MDX files support:
- ESM -
importandexportblocks at the start of a line (a block ends at the next blank line) are hoisted into the page module, soexport const version = "1.2"can be used by the rest of the file. - Inline JSX - components inside paragraphs, with Markdown inside their
children:
Status: <Badge>**beta**</Badge>. - Expressions -
{...}in text and attributes.{frontmatter.title}and exported literal constants are resolved at build time (so they also work in headings and the search index); other expressions are emitted as runtime expressions. Escape a literal brace as\{. - Comments -
{/* a comment */}is dropped.
An unterminated { or an unsupported export default is a build error with
the file, line and column. Plain .md files do not treat braces specially.
A list, quote, table or code block can sit directly inside a multi-line JSX element; the element's closing tag still closes it:
<Note>
- first
- second
</Note>If compiled markdown is not valid JSX, the error says its line and column refer to the generated code, not your file.
The frontmatter title and description become the page's <title> and meta
description. Components can be used inline:
# A page with a component
Here is a callout rendered from JSX:
<div class="callout">
<strong>Heads up!</strong> You can mix Markdown and JSX in one file.
</div>MDX files can also import components:
import { Callout } from '../../components/callout';
<Callout type="tip">Imports work too.</Callout>#Configuration
markdown: {
gfm: true,
headingAnchors: true,
admonitions: true,
codeHighlight: true,
math: false,
}These options apply to page-level .md/.mdx files, imported ones, content
collections and the docs plugin alike.
#Links, images and code
- Link, image and
<https://...>autolink destinations are checked against a scheme allow list (http,https,mailto,tel,ftp, relative); anything else, such asjavascript:ordata:, is rendered as plain text. - A relative image (
) is resolved against the markdown file, copied to/assets/with a content hash and linked there (prefixed withbasePath). A missing file is left as written. Root-relative links and images also get the base path, so[Guide](/docs/guide/)works under a sub-path. - Fenced code takes
title="app.ts"and highlighted lines:```ts {1,3-5}marks those lines (.hl) and addsdata-highlight-lines. A title shows as a header. A block or table that is likely to scroll becomes a focusable group with a name; short ones add no tab stop.mdx,astroandprismafences are highlighted with the closest built-in language.
For how Markdown and MDX are parsed and compiled, see Contributing -> Architecture.
#Content collections
getCollection("name") entries expose html, rendered with the same
renderer (highlighted code blocks, task lists, MDX expressions that resolve at
build time). Because html is a plain string, MDX components cannot render in
it: they are omitted and each one produces a warning with the file, line and
column. A collection entry that violates its schema, or an MDX syntax error,
fails the build (and krate check) instead of being skipped.
Collection data is folded into the page at build time and is never copied to the browser: a page that only reads one entry ships none of the collection (or its draft entries) in its JavaScript.
A chain that depends on a browser-only value (for example
getCollection("blog").filter((p) => p.data.tag === tag()) with a signal) cannot
be folded, so it runs in the browser and the entries are copied into the page
script. Krate warns with KR8810 at the call and ships only the fields the page
mentions: body and html stay out unless the code reads them, but every
entry, drafts included, is still part of the script. Filter with build-time
values, or compute the list on the server, to keep the collection out of the
browser.
Last updated: 2026-11-17
Contributors: Noinkin