Quartz: Turn your markdown files into a website
Quartz turns a folder of Markdown files into a fast static site with search, backlinks and a graph view. Here is how it works, where it fits, and what to watch out for.
Quartz is a free, open-source static site generator for publishing a folder of Markdown files as a full website. Point it at a directory and it produces plain HTML, CSS and JavaScript: no database, no server runtime, nothing to keep patched.
The official site is itself built with Quartz.
What you get out of the box
- Full-text search across every page
- Bidirectional links and backlinks
- Callouts, tags, and per-page tables of contents
- An interactive graph view of how pages connect
- Dark and light modes, plus a reader mode
- Syntax highlighting, math, and diagram rendering
- Sitemaps, RSS, and per-page social preview images
How it works
Quartz is a pipeline, and understanding the stages makes the config far less mysterious:
- Content — Markdown files are read from a single content folder. Folder structure becomes URL structure.
- Parsing — plugins parse each file: frontmatter, wikilinks, callouts, code blocks, embeds.
- Transformation — plugins rewrite links, generate tables of contents, resolve the graph, and build the search index.
- Emission — each page is rendered to HTML and written to an output folder alongside the assets and indexes.
Because every step is a plugin, you can add or disable behaviour without touching the core. The whole build is deterministic, so the output can be cached and served by anything from GitHub Pages to a small static file server.
Customising it
- Site settings live in a single YAML config: page title, base URL, locale, theme colours, plugin list and their order.
- Styling is SCSS. A small override file is enough; you rarely need to fork a theme.
- Fonts are handled by a plugin. The default pulls from Google Fonts, while self-hosted font files keep the site working offline and avoid third-party requests.
- Layout is controlled by plugin order and position (left sidebar, right sidebar, footer), so navigation, search and the graph can be rearranged rather than rebuilt.
Things worth knowing
- Frontmatter plugins matter. Quartz reads page metadata from frontmatter plugins; disable the one that does it and every page falls back to a generic title.
- Static means static. Edits appear only after a rebuild, so pair it with a script or a watcher if you publish often.
- Base URL affects every link. Set it correctly before building; a wrong path prefix breaks assets and internal links even though the pages exist.
- Privacy is a deployment choice. The build output contains whatever is in the content folder, so decide who can reach the site before you publish: a private network, an authenticated hostname, or the open web.
When it is a good fit
Quartz works best when you have many pages that link to each other and are meant to be read. A few patterns where it shines:
- eBook — chapters read in the browser instead of a PDF: text reflows to any screen size, so no pinch-zooming a fixed page; search, links and a table of contents actually work; and readers get the current version instantly with nothing to download, no app required, and no stale file to keep track of.
- Documentation — syntax highlighting, search across every page, and anchor links make reference material quick to scan. Folder structure maps directly onto a docs hierarchy.
- Digital garden or personal wiki — backlinks and the graph view are the point: ideas show up as connected notes rather than a chronological feed, and old pages keep their URLs.
- Course or lecture notes — math, diagrams, and callouts are supported natively, so formulas and worked examples render properly while students get a searchable site instead of a pile of PDFs.
- Research notebook — long projects accumulate linked findings, sources, and definitions; tags and backlinks keep them traceable, and static output stays readable years later with no dependencies.
- Team handbook or knowledge base — internal policies and processes change often but rarely need logins. Markdown in version control, a rebuild, and the site is current for everyone.
- Tutorial or book companion site — code blocks, embeds, and hover previews suit step-by-step walkthroughs where readers jump between sections.
- Portfolio of writing — an archive of essays and talks with stable, cheap hosting; no plugin updates, no database to maintain.
Poor fits: anything needing comments, user accounts, per-user content, or server-side logic (those can be bolted on by embedding external services), and small single-page sites, where a static generator is more machinery than the job needs.