Content and Markdown
Chinese version · English
Everything lives under content/, with four accepted extensions: .md, .markdown, .html, .htm. There is no required directory layout — but directories decide URLs, so the conventions are worth spelling out.
Directories and URLs
| Source | URL | Output |
|---|---|---|
content/index.md |
/ |
dist/index.html |
content/about.md |
/about/ |
dist/about/index.html |
content/about/index.md |
/about/ |
dist/about/index.html |
content/posts/hello.md |
/posts/hello/ |
dist/posts/hello/index.html |
content/notes/2026/a.md |
/notes/2026/a/ |
dist/notes/2026/a/index.html |
content/raw.html |
/raw.html |
dist/raw.html |
In three rules: index collapses into the directory itself; the extension is dropped and a trailing slash added; .html is left alone (so the link matches the file).
To pin an address, say so in front-matter:
1 |
|
url, permalink and slug are all accepted and normalised (leading slash, trailing slash where needed).
Non-ASCII paths work too: content/notes/getting-started.md becomes /notes/getting-started/, and percent-encoded directory names are decoded on the way to disk — static servers decode the URL before looking for a file, so a literal %E7%AC%94%E8%AE%B0 directory would 404.
front-matter
YAML between two --- lines. Every field is optional:
1 | --- |
| Field | Type | Meaning |
|---|---|---|
title |
string | Title; falls back to the file name |
date |
date | Publish date, used by feeds and sorting |
published |
date | Alias of date |
updated |
date | Last update, becomes sitemap lastmod |
description |
string | Summary, beats the automatic excerpt |
summary |
string | Alias of description |
tags |
array or CSV | Tags; [a, b] and a, b both work |
category |
string | Category, single value |
series |
string | Series, single value |
layout |
string | Layout file, defaults to defaults.layout |
weight |
number | Sort weight, lower first |
order |
number | Alias of weight |
draft |
bool | true skips production builds |
toc |
bool | false disables the table of contents for this page |
type |
string | page keeps it out of lists, feeds and prev/next |
url / permalink / slug |
string | Set the address by hand |
group / section |
string | Sidebar group name for the docs theme |
type: page is the useful one: an “About” or “Links” page marked this way disappears from the home list, the feeds and the prev / next chain.
Two date details that bite:
- A date-only value is a local calendar day.
date: 2026-11-10means local midnight, so a site west of UTC does not render the post a day early.2026-11-10 09:00is built in local time as well; a timestamp with an explicit offset (2026-11-10T09:00:00Z) keeps its value. - A UTF-8 BOM does not break parsing. Several Windows editors save as “UTF-8 with BOM” by default; front-matter is still recognised because the BOM is stripped before the first
---is looked for — the title does not fall back to the file path.
Posts, pages and drafts
Content has three roles, and the difference is two or three front-matter fields:
| Role | Create with | Key fields | Behaviour |
|---|---|---|---|
| Post | xfm new "Title" |
layout: post.html |
In the home list, feeds, search, prev/next, related posts |
| Page | xfm new page about |
layout: page.html + type: page |
Own URL /about/, in no list or feed |
| Draft | xfm new draft "Title" |
draft: true |
Rendered by xfm dev, skipped by xfm build |
Pages and posts share the same layout machinery; the only difference is whether they join the aggregates. site.posts excludes everything with type: page, and sitemap / rss / search / related skip them too. So to get a page into the navigation, add it to site.nav yourself:
1 | site: { |
Scaffolds
The starter content produced by xfm new is not hard-coded — it comes from scaffolds/<layout>.md in the site root, mirroring Hexo’s scaffolds/:
1 | scaffolds/ |
Three placeholders are available:
| Placeholder | Replaced with |
|---|---|
{{ title }} |
The title |
{{ date }} |
Current time, local timezone |
{{ layout }} |
Layout file name, e.g. post.html |
Edits apply on the next xfm new (it is a separate process and reads the file each time). A site without scaffolds/ uses the built-in templates, so old sites need no migration; xfm create writes the three defaults for new ones.
Missing keys are filled in automatically: title, date, layout, type: page, draft. A template containing nothing but a heading still produces a page that behaves correctly — never a page published as a post, never a draft that slips out.
Drafts
1 |
|
Production builds (xfm build) skip drafts; xfm dev renders them, so you can preview locally without leaking anything to the live site. To include drafts in a build, set buildDrafts to true.
xfm new draft "Title" writes the field for you (xfm new "Title" --draft is equivalent).
Ordering and prev/next
Page ordering is fixed, in three tiers:
- The home page (
/) is always first; - The rest sort by
weightascending — documentation sites use this for chapter order; - Ties fall back to
datedescending.
prev / next follow the same order and only link posts together (home page, type: page and pages without a date are excluded). Templates read page.data.prev.url / page.data.prev.title directly.
Markup
The body is standard Markdown with the usual GFM support. On top of that:
Callouts
1 | ::: tip Optional title |
The kind decides colour and icon; the title is optional. details is collapsible — good for long appendices.
Code blocks
Fences accept a language tag and a title:
1 | ```js app.js |
Language aliases are normalised, case-insensitively:
| Family | Accepted tags |
|---|---|
| JavaScript | js javascript jsx ts tsx |
| Back end | java c cpp csharp go golang rust rs swift kotlin scala php python py |
| Shell and config | bash sh shell json yaml yml |
| Markup and style | html xml svg vue css scss markdown md text |
An unknown language is not an error — it degrades to escaped monospace text. Meta information on the fence line (highlight ranges such as {1,3-5}) is ignored and does not affect the build.
Indented code blocks
When you would rather not write a fence, four leading spaces or a tab also open a block — inside and outside list items:
1 | Under a normal paragraph: |
Inside a list, indent four columns past the item’s content position — that position depends on the marker width (2 for - , 3 for 1. ):
1 | - Install: |
You can also put 5 spaces after the marker so the item starts with a code block: 1–4 spaces after the marker are padding, and the fifth onwards belongs to the content — that one extra column is what makes the first line a code block:
1 | - const a = 1; |
Both produce a code block inside the li (<li><div class="code-block">…</div></li>). Indented quotes, ::: containers and rules after a blank line inside an item work the same way — they all go to the block parser.
Up to three leading spaces on a paragraph line are treated as indentation and dropped, so they never leak into <p>.
Reference links
1 | I have been tinkering with [static site generators][ssg] and reordered the [docs][docs]. |
Definition lines never appear in the body. The shorthand [ssg] works too — when the link text is the identifier, the second pair of brackets can go.
A definition only counts at the start of a paragraph. Dropped into the middle of one, [ssg]: /x stays literal text and does not register a reference — that is what CommonMark requires, and it also prevents a sentence from being cut in two. To keep a definition mid-document, give it its own paragraph.
Footnotes
1 | Drop a marker in the text[^note] and the note appears at the end. |
Notes can hold block content too — a second paragraph, a sub-list, a code block — and it must be indented by four spaces (or a tab):
1 | [^note]: First paragraph of the note. |
1–3 spaces do not mean block content; they still mean “next line, same paragraph”, so existing prose never breaks. A following paragraph with no indentation stays an ordinary paragraph.
Also supported
- Setext headings:
====(level 1) or----(level 2) under a paragraph. Inside a list item,- Headingplus an indented---keeps that meaning instead of becoming a rule. - Indented code blocks: four spaces or a tab, inside or outside lists — see the Indented code blocks section above.
- Loose lists: blank lines between items, or inside one, no longer split or end the list; affected paragraphs are wrapped in
<p>per CommonMark’s tight/loose rule, and content indented to the item’s content position still belongs to that item. A blank line after a list still ends it. - Escapes:
\*not italic\*,\`not code`. - Task lists:
- [x] done/- [ ] todo, with continuation lines and nesting. - List continuation: indented and lazy (unindented) continuations join the same item, but lazy continuation is no longer allowed after a blank line; ordered lists keep their start number (
3.emitsstart="3"). - Tables: standard GFM tables with alignment markers.
Heading anchors
Level 2 and 3 headings get an id, and non-Latin headings still produce readable anchors (duplicates get a numeric suffix). Headings are also collected into page.toc, which the theme uses to render the right-hand outline — so toc: false affects the outline, not the anchors.
Relative links
Relative paths in Markdown are resolved against the source file’s location and rewritten to site URLs:
1 | See [the previous post](./hello.md) and [the diagram](../../assets/diagram.png). |
Rules:
- Links with a scheme, protocol-relative links, root-relative links (
/x) and pure anchors (#x) are left alone; - Everything else resolves from the current source directory, then maps to the target page’s URL;
- A
.mdlink pointing at a file that does not exist is left as written — a typo does not silently become some other path.
The upshot: move files around freely, and as long as the relative relationships hold, the links keep working.
Static files
Anything under public/ is copied verbatim to the output root — favicon.ico, robots.txt, self-hosted fonts, images:
1 | public/ |
Theme assets take a different route: they live in the theme’s assets/ and end up under site.assets (default /assets/).
Excerpts and reading time
List pages need an excerpt and a reading time, both computed during the scan rather than at render time:
- Excerpt: front-matter
descriptionwins; otherwise the first 140 characters of the body, with an ellipsis. Code blocks, link targets, reference definitions and footnote definitions are stripped first — otherwise you would see[home]: https://…in the summary. - Reading time: 350 characters per minute, minimum one minute.
Both are exposed as page.excerpt and page.readTime.
Writing advice
- One topic per post, keywords in the title, and a full sentence in
description(it feeds lists, feeds and search snippets). - Chain a series with
seriesand order it withweight— the/series/<name>/page then becomes a natural reading path. - Split long posts with level 2 and 3 headings: the outline only collects those two levels.
评论