Command line
Chinese version · English
Every command is xfm <command> [directory] [options]. The directory defaults to the current working directory — inside a site root, xfm build is enough.
1 | xfm --help # all commands and options |
Commands at a glance
| Command | Purpose | Common options |
|---|---|---|
xfm create [dir] |
Scaffold a site | --template=blog or --template=docs, --title= |
xfm dev [dir] |
Dev server with SSE hot reload | --port= |
xfm build [dir] |
Production build | --dev |
xfm new [layout] <title> |
New post, page or draft | --layout=, --dir=, --slug=, --draft, --force |
xfm clean [dir] |
Remove output and incremental cache | — |
xfm info [dir] |
Print the resolved configuration | — |
Aliases
To keep the Hexo muscle memory working, the most natural gestures do what you expect instead of dumping help text:
| Alias | Equivalent |
|---|---|
init |
create |
generate / gen |
build |
serve / server / preview |
dev |
Mistype a command and the CLI guesses by prefix and edit distance — “did you mean xfm build?” — instead of failing silently.
create
1 | xfm create my-blog # blog template |
The two templates:
--template |
Look | Good for |
|---|---|---|
blog (default) |
List home page, article page, right-hand TOC | Personal blogs, technical notes |
docs |
Left grouped sidebar, prose column | Product docs, knowledge bases |
The scaffold never overwrites existing files, so re-running it inside a half-finished directory is safe. When it finishes it lists the plugins you are still missing and the exact npm i command.
“Is this directory already a site?” is decided by hasConfig(), which recognises six forms: xfm.config.mjs / .js / .cjs / .json, config.js, and an "xfm" field in package.json. On a match create stops and says so; only --force overwrites. Earlier versions checked .mjs alone, so a site configured any other way was treated as empty and overwritten.
Besides the site skeleton, xfm create also writes three content templates under scaffolds/ (post.md, page.md, draft.md) — those are what xfm new reads — plus a .gitignore (node_modules/, dist/, .xfm/, OS junk). An existing .gitignore is left untouched.
dev
1 | xfm dev |
Three things happen on start:
- An in-memory build (nothing written to disk), usually a few hundred milliseconds;
- An HTTP server on
http://127.0.0.1:4173/; - Watchers on
content/,themes/,plugins/and the config file, pushing changes over SSE — the page reloads while keeping scroll position.
The granularity is worth knowing: editing Markdown rebuilds only the affected pages; editing CSS swaps the stylesheet without a reload; editing templates or config recomputes everything. A single page rebuild measures 2–7 ms.
server.host / server.open are honoured too — open: true launches a browser after start.
build
1 | xfm build |
--dev does not mean “build a dev version” — it means “let the incremental cache work in this mode too”. Output is environment-agnostic; only a few plugins (giscus, analytics) decide whether to inject third-party scripts based on mode.
A typical run:
1 | xfm build |
Line by line:
| Line | Meaning |
|---|---|
| Pages | Content pages + taxonomy pages (tag / category / series) + pagination + index pages |
| Plugins | Plugins that actually loaded; when empty you get an install hint |
| Extra | Non-page files written by plugins, folded after six |
| Assets | Files copied from the theme’s assets/ and the site’s public/ |
| Unchanged | Files skipped because the content already matches the old output; the line disappears when everything is rewritten |
| Workers | Present only when the page count crosses workerThreshold and no plugin blocks the pool |
| Cached | Pages skipped this run; only appears on a cache hit |
new
The shape matches hexo new [layout] <title>: when the first positional argument is a layout you can omit --layout, and for a plain post you write nothing extra.
1 | xfm new "My first post" # post → content/posts/my-first-post.md |
The three layouts:
| Layout | Lands in | front-matter written | Meaning |
|---|---|---|---|
post (default) |
content/posts/<slug>.md |
layout: post.html |
A post: home list, feeds, search, prev/next |
page |
content/<slug>.md |
layout: page.html, type: page |
A fixed page: own URL, never in a list |
draft |
content/posts/<slug>.md |
layout: post.html, draft: true |
Draft: skipped by xfm build, previewed by xfm dev |
page only became a first-class command in 0.4.8. Before that, “About” or “Links” pages had to be placed in the content/ root by hand with a type: page you had to remember — miss it and the page quietly became a post in the list and the feed. Now the layout does both.
Behaviour details:
- A layout only applies when the first word is a known layout and a second argument exists:
xfm new pageis a post titled “page” (matching Hexo), whilexfm new page aboutis a page. Use--layout=to force it. - Multi-word titles stay whole:
xfm new My First Postcreates “My First Post” instead of truncating after the first word. - A misspelled layout gets a suggestion:
xfm new apge aboutsays there is no layout namedapge, treats the input as a title, and points atxfm new page <title>. - slug generation: lowercased, non-alphanumerics collapsed into
-, leading and trailing dashes trimmed; a title with no usable characters falls back topost. - Duplicate names do not fail:
-2,-3are appended; use--forceto overwrite. - Titles are escaped: characters such as
:and#are wrapped in double quotes when written into front-matter. - It must run inside a site: outside one it errors out, prints the path, points at
xfm create, and creates nothing. Earlier versions wrotecontent/posts/<slug>.mdinto an empty directory and claimed you could just build — while the build failed. --diris normalised and bounded:--dir=docs\suband--dir=docs/subare the same thing, and the address in the summary is the real URL. Climbing out of the content directory with..is refused (--dir 不能跳出内容目录).
The generated file looks like this (the starter body no longer repeats an # H1, since the theme renders it from page.title):
1 | --- |
The command prints the layout and the resulting URL so you can confirm where it landed:
1 | xfm new page about |
Customising starter content with scaffolds
The initial content comes from scaffolds/<layout>.md in the site root — the same idea as Hexo’s scaffolds/ — with three placeholders:
| Placeholder | Replaced with |
|---|---|
{{ title }} |
The title |
{{ date }} |
Current time, local timezone |
{{ layout }} |
Target layout file, e.g. post.html |
xfm create writes scaffolds/post.md, scaffolds/page.md and scaffolds/draft.md, and edits take effect immediately — no restart, since xfm new is a separate process that reads the file each time. A site without the directory falls back to the built-in templates, so nothing has to be migrated.
Missing keys in a custom scaffold are filled in automatically (title, date, layout, type: page, draft). Otherwise a template containing only a title could produce a page that publishes like a post, or a draft that goes live.
clean
1 | xfm clean |
Two things disappear: outDir (default dist/) and the incremental cache directory .xfm/. When something “changed but still renders the old page”, clean is the fastest way to rule the cache out.
info
1 | xfm info |
Read-only: no build, nothing written. The “Config” line tells you which file was actually read — if it says defaults, the site has no config file and everything comes from built-ins.
Exit codes
| Situation | Code |
|---|---|
| Success | 0 |
| Unknown command / option | 1 |
| Build or render error | 1 |
new / build outside a site |
1 |
Usable directly in CI: errors the engine raises itself (a declared plugin that is not installed, say) print a one-line fix instead of a screenful of stack trace.
评论