Handbook / Getting started
Installing Lumen
Last updated Jul 20 · 6 min read
Lumen is a fictional static-site generator that exists so this page has something to document. It compiles a folder of markdown into a site with one config file and no build graph to babysit. Install it globally with your package manager of choice:
npm install -g @lumen/cli
lumen init my-site
cd my-site && lumen servenode --version before filing a bug about
the installer.Configuration
Everything lives in lumen.config.js.
The defaults are deliberately boring: content in content/,
output in dist/, and a single theme slot. Most sites
never need more than the site title, a base URL, and a
theme name.
Themes
A Lumen theme is one stylesheet — the markup is frozen. If that sounds familiar, it should: this documentation page is itself a theme-lab fixture, and the constraint is the whole point.
“The less a theme is allowed to change, the more themes you can afford to have.” — The Lumen Handbook, chapter 1
dist/ feels productive right up until the next build
deletes your afternoon.CLI flags
| Flag | Description | Default |
|---|---|---|
--port | Dev-server port | 4000 |
--theme | Theme stylesheet to apply | baseline |
--drafts | Include draft pages | false |
--strict | Fail the build on broken links | true |
Troubleshooting
Ninety percent of Lumen issues are a stale cache. The other ten
percent are also a stale cache, but in a different folder. Run
lumen clean first, then read the
error message — it usually says exactly which file it choked on.
Still stuck? The fictional community forum is full of fictional people with the same problem.