Quartz (Obsidian SSG): Comprehensive Evaluation for a 178-Page Business Wiki

Executive Summary

Quartz v4 is the most Obsidian-faithful static site generator available — it handles [[wiki links]] with spaces, aliases, heading anchors, subdirectory organisation, YAML frontmatter, graph view, backlinks, and full-text search out of the box with zero conversion steps. For a 178-page business wiki built in Obsidian, it is the lowest-friction path from vault to published website. However, its default aesthetic skews “developer’s digital garden,” and making it feel like a professional business tool for a CEO audience requires meaningful CSS and layout customisation. The project is actively maintained but shows signs of a one-maintainer bottleneck — 327 open issues, v5 in early planning, and a commit cadence of roughly monthly merges.

The strongest alternative is MkDocs with the Material theme, which offers a more polished default UX and a larger ecosystem, but requires third-party plugins for wiki link conversion, backlinks, and graph view. Quartz wins on Obsidian fidelity; MkDocs Material wins on professional presentation and long-term ecosystem stability.

Quartz Capabilities and Features

Current Version

Quartz v4 is the current production version, rewritten from scratch in TypeScript (v3 was Hugo-based). The last formal release is v4.0.8 (August 2023), but active development continues on the v4 branch with the most recent commit on 4 March 2026. The project has 11,782 GitHub stars, 3,669 forks, and 30 contributors under an MIT licence. It requires Node v22+ and npm v10.9.2+. (Quartz homepage)

Feature Matrix

Feature	Status	Details
Wiki links `[[Page Name]]`	Built-in	Resolved by the CrawlLinks plugin; supports shortest, absolute, and relative path resolution
Wiki links with spaces	Supported	`[[Path to file]]` resolves to `Path to file.md` or `Path-to-file.md` (Wikilinks docs)
Aliases `[[page\|display text]]`	Supported	Produces a link to the file with the overridden display text
Heading links `[[page\#heading]]`	Supported	Links to a specific anchor within the target file
Block references `[[page\#^block-id]]`	Supported	Links to specific block IDs
Transclusions `![[page]]`	Supported	Embeds full pages, heading sections, or specific blocks inline
Subdirectory organisation	Supported	Content goes in `/content` folder; subdirectories preserved in URL structure
YAML frontmatter	Built-in	Parsed by the Frontmatter transformer plugin; native fields: `title`, `description`, `aliases`, `tags`, `draft`, `date`, `permalink`, `cssclasses`
Full-text search	Built-in	Powered by Flexsearch; returns results in under 10ms for sites up to 500,000 words; separate indexes for title, content, and tags; CJK tokenisation; keyboard accessible
Graph view	Built-in	Local and global modes; node radius proportional to link count; visited-node highlighting; interactive
Backlinks	Built-in	Displays incoming links with rich popover previews; hideable when empty
Table of contents	Built-in	Auto-generated from H1–H3; highlights current scroll position; per-page disable via `enableToc: false` frontmatter
Explorer (file tree)	Built-in	Collapsible sidebar with customisable sort, filter, and map functions; folder display names from `title` frontmatter in `folder/index.md`
Breadcrumbs	Built-in	Folder hierarchy navigation at top of each page
Dark mode	Built-in	Respects OS preference; manual toggle persisted in localStorage
Mobile responsiveness	Built-in	Three-column layout collapses at configurable breakpoints (mobile < 800px, desktop > 1200px) (Layout docs)
SPA routing	Built-in	Prevents unstyled content flashes via micromorph diffing
Popover previews	Built-in	Rich content previews with formatting, images, and heading navigation
Callouts	Built-in	Obsidian-style admonitions via ObsidianFlavoredMarkdown plugin
LaTeX	Built-in	KaTeX or MathJax rendering
Mermaid diagrams	Built-in	Native support
Syntax highlighting	Built-in	Code block syntax highlighting
RSS feed	Built-in	Generated from content
Comments	Built-in	Integrates with external comment providers
i18n	Built-in	Locale configuration for date formatting and UI strings
Docker support	Built-in	Containerised builds
Private pages	Built-in	Via `draft: true` frontmatter or `ignorePatterns` glob config

Customisation Architecture

Quartz uses a plugin-based architecture with three plugin types (Architecture docs):

Transformers: Process Markdown content (frontmatter parsing, wiki link resolution, LaTeX rendering)
Filters: Include/exclude content (draft filtering, explicit publish)
Emitters: Generate output files (HTML pages, RSS, tag listings, content index)

Layout is configured in quartz.layout.ts using JSX components placed in sections: header, beforeBody, left, right, afterBody. Each component (Explorer, Graph, Search, TOC, Backlinks, Darkmode, Breadcrumbs) can be repositioned, reconfigured, or removed entirely. Custom components can be written in TSX/JSX with Preact. (Layout docs)

Theme customisation in quartz.config.ts provides:

Typography: Separate Google Fonts for title, headers, code, and body text
Colours: Nine semantic colour tokens (light, lightgray, gray, darkgray, dark, secondary, tertiary, highlight, textHighlight) with separate light/dark mode palettes
CDN caching: Toggle between Google CDN fonts and self-hosted (Configuration docs)

Deeper styling uses Sass: base styles in quartz/styles/base.scss, custom overrides in quartz/styles/custom.scss.

Setup and Configuration

Initial Setup (Step-by-Step)

# 1. Clone the Quartz repo
git clone https://github.com/jackyzha0/quartz.git my-wiki
cd my-wiki
 
# 2. Install dependencies
npm i
 
# 3. Initialise (interactive — choose "empty Quartz" or "copy existing vault")
npx quartz create
 
# 4. Copy your Obsidian vault content into /content
cp -r /path/to/vault/* content/
 
# 5. Configure in quartz.config.ts (site title, base URL, theme)
 
# 6. Build and preview locally
npx quartz build --serve
# → Site available at http://localhost:8080
 
# 7. Build for production
npx quartz build
# → Static files in /public

The npx quartz create wizard asks two questions: whether to start empty or import content, and the preferred link resolution method (shortest path, absolute, or relative — matching Obsidian’s three modes). (Quartz getting started)

Content Structure for Subdirectories

For a wiki organised as entities/, concepts/, sources/, analysis/, decisions/:

content/
├── index.md              ← Homepage
├── entities/
│   ├── index.md          ← Folder landing page (title from frontmatter)
│   ├── Company-A.md
│   └── Person-B.md
├── concepts/
│   ├── index.md
│   └── Market-Analysis.md
├── sources/
├── analysis/
└── decisions/

Each index.md within a folder sets the folder’s display name in the Explorer sidebar via its title frontmatter field. Without an index.md, the folder name is used as-is. (Explorer docs)

Configuration for This Wiki

Key settings in quartz.config.ts:

const config: QuartzConfig = {
  configuration: {
    pageTitle: "Business Wiki",           // Site title
    enableSPA: true,                       // Smooth navigation
    enablePopovers: true,                  // Rich link previews
    locale: "en-AU",                       // Australian locale
    baseUrl: "wiki.example.com",           // Production domain
    ignorePatterns: [".obsidian", "_templates", "private"],
    defaultDateType: "modified",           // Show last-modified date
    theme: {
      typography: {
        header: "Inter",                   // Clean professional font
        body: "Inter",
        code: "JetBrains Mono",
      },
      colors: {
        // Custom brand palette here
      }
    }
  }
}

Learning Curve

For a developer doing initial setup: 2–4 hours to get a working site with content. Customising theme colours and fonts: another 1–2 hours. Restructuring layout (moving/removing components): requires reading the layout docs and modifying JSX — half a day for someone comfortable with React-like syntax. Creating custom components: requires TypeScript/JSX knowledge.

For a non-technical CEO post-setup: editing Markdown files is straightforward. Running npx quartz build --serve for local preview is a single terminal command. Publishing via npx quartz sync pushes to GitHub. No code changes needed for day-to-day content work.

Deployment Options

Quartz supports all major static hosting providers. The hosting documentation covers each in detail.

Provider	Build Command	Output Dir	Custom Domain	Community Recommended
Cloudflare Pages	`npx quartz build`	`public`	Yes (Cloudflare DNS)	Yes — fast, generous free tier
GitHub Pages	Via GitHub Actions YAML	`public`	Yes (A/CNAME records)	Yes — simplest if already on GitHub
Vercel	`npx quartz build`	`public`	Yes	Yes — requires `vercel.json` for clean URLs
Netlify	`npx quartz build`	`public`	Yes	Yes — straightforward
GitLab Pages	Via `.gitlab-ci.yml`	`public`	Yes	Less common
Self-hosted (Nginx/Apache/Caddy)	`npx quartz build`	`public` → copy to server	Yes	For full control

Build/Deploy Pipeline

The typical workflow:

Edit Markdown in Obsidian (locally)
Run npx quartz sync — commits and pushes to GitHub
GitHub Actions / Cloudflare Pages / Netlify detects the push
Runs npx quartz build on the server
Deploys the /public directory as a static site

Build time for 178 pages: estimated 5–15 seconds. Quartz uses worker threads when content exceeds 128 files, with batches of 128 processed in parallel. (Architecture docs)

Recommended: Cloudflare Pages

The Quartz community favours Cloudflare Pages for production deployments:

Generous free tier (unlimited bandwidth, 500 builds/month)
Automatic HTTPS and CDN
No trailing-slash redirect issue (unlike GitHub Pages, which generates file.html rather than file/index.html and breaks trailing-slash links)
Deploy previews for branches

Caveat: Cloudflare performs shallow clones by default. If using git-based timestamps, prepend git fetch --unshallow && to the build command. (Hosting docs)

Limitations and Known Issues

Critical for This Wiki

Issue	Severity	Details
Case-sensitive wiki links	High	Obsidian treats `[[foo]]` and `[[Foo]]` identically; Quartz does not — mismatched casing produces 404 errors. Issue #2316, Issue #1122. An open PR #2327 forces lowercase URL slugs but is not yet merged.
No Dataview support	High	Dataview queries (`dataview`, `dataviewjs`) are not rendered. Issue #102 — 30 thumbs-up, 21 comments, still open. If the wiki uses Dataview, output will show raw query blocks.
No Canvas support	Medium	Obsidian Canvas files are not converted. Issue #927 — 24 thumbs-up, 32 comments, still open.
Aliases + backlinks incompatibility	Medium	Backlinks do not resolve correctly when pages are linked via aliases. Issue #2230.
Image wikilinks with underscores	Low	`![[image_name.png]]` fails to render if the filename contains underscores. Issue #2305.
Mobile Explorer overflow	Low	Adding non-default components to the left layout causes overflow on mobile. Issue #2269.

Workaround for Case Sensitivity

Until PR #2327 is merged, the practical workaround is to ensure consistent casing in the Obsidian vault. The Obsidian plugin “Linter” can normalise link casing across the vault. Alternatively, apply the PR’s one-line change locally: force all slugs to lowercase in quartz/util/path.ts.

Community-Reported Pain Points

Graph view crashes on iOS Safari when expanding to global view (Issue #2257)
Dead links to non-existent pages render as clickable links leading to 404 pages; no option to render them as plain text or strikethrough. Issue #454 — 14 thumbs-up, 15 comments, open since 2022. A community workaround converts dead links to <span> tags.
cssclasses frontmatter not applied to output (Issue #2332)
No per-folder RSS feeds (Issue #866 — 25 comments, 10 thumbs-up)
No password-protected notes (Issue #1481 — 21 comments)
Inlined CSS/JS — each page includes thousands of lines of inlined scripts and styles; no easy way to externalise them

Maintenance Status

Metric	Value
Stars	11,782
Open issues	327
Contributors	30
Last commit	4 March 2026
Commit cadence	Roughly monthly merge batches
Last formal release	v4.0.8 (August 2023) — no tagged releases since
v5 plans	Early discussion: npm package distribution, pnpm migration, community org
Primary maintainer	Jacky Zhao (solo maintainer with community PRs)
Discord	Active community server

Risk assessment: Quartz is a healthy open-source project but is essentially maintained by one person. The 327 open issues and absence of tagged releases since 2023 suggest a maintainer bandwidth constraint. v5 is in early ideation with no timeline. For a business-critical wiki, this is an acceptable risk given the MIT licence (you can fork and maintain independently), but contrasts with MkDocs Material’s corporate-backed sustainability.

MkDocs 2.0 disruption note: MkDocs itself announced a ground-up rewrite (MkDocs 2.0) that is incompatible with Material for MkDocs and removes the plugin system. The Material theme maintainer has flagged this as a major concern. This introduces ecosystem uncertainty for MkDocs Material that partly neutralises its “safer long-term bet” advantage over Quartz.

Head-to-Head: Quartz vs Alternatives

Comparison Matrix

Criterion	Quartz v4	MkDocs + Material	Docusaurus	Eleventy + obsidian-export	Hugo + converter
Wiki links (native)	Yes	No (plugin needed)	No (plugin needed)	No (pre-process step)	No (pre-process step)
Spaces in links	Yes	Yes (via roamlinks)	Yes (via gl0bal01 plugin)	Yes (via obsidian-export)	Partial (absolute paths required)
Aliases	Yes	Yes (via mkdocs-publisher)	Yes	Yes	Yes
Heading anchors	Yes	Yes	Yes	Approximate	Yes
Subdirectory support	Native	Yes	Yes	Yes	Yes (preserves structure)
Frontmatter	Native (Obsidian fields)	Native (YAML)	Native (YAML)	Copied as-is	Copied by converter
Search engine	Flexsearch (client-side)	Lunr.js (client-side)	Algolia (cloud) or local	Pagefind/Lunr (custom)	Pagefind/Lunr (custom)
Graph view	Built-in	Community plugin	Vaultusaurus	None	None
Backlinks	Built-in	Community plugin	None	Custom code	Custom code
Dark mode	Built-in	Built-in	Built-in	Custom CSS	Theme-dependent
Mobile responsive	Built-in	Built-in	Built-in	Custom	Theme-dependent
Default visual polish	Medium	High	High	None	Theme-dependent
Setup complexity	Low	Medium	Medium–High	High	High
CEO self-service	Yes (Markdown + sync)	Yes (Markdown + build)	Partly	No	No
GitHub stars	11.8k	26.5k	64.5k	19.5k	87.5k
Ecosystem risk	Solo maintainer, v5 uncertain	MkDocs 2.0 breaking changes	Meta-backed, stable	Stable, small core team	Very stable

Verdict by Criterion

Obsidian fidelity: Quartz wins decisively. It is the only tool that processes [[wiki links]] directly without a conversion step or plugin stack. The ObsidianFlavoredMarkdown transformer handles callouts, Mermaid, highlights, and wikilinks natively.

Professional UX out of the box: MkDocs Material wins. Its default theme looks like production documentation; Quartz’s default looks like a digital garden. Docusaurus is also strong here.

Search quality: Quartz’s Flexsearch is fast and functional but basic. MkDocs Material’s Lunr integration offers search suggestions, highlighting, and boosting. Docusaurus + Algolia is the most powerful but requires a cloud service. For a 178-page private wiki, all three are adequate.

Long-term maintainability: All options carry some risk. Quartz is solo-maintained. MkDocs faces the MkDocs 2.0 uncertainty. Docusaurus requires React knowledge. Hugo and Eleventy are stable but require more custom code for Obsidian features.

Recommendation: Quartz is the right choice for this project — its Obsidian fidelity eliminates the conversion layer that every alternative requires, and 178 pages is well within its performance envelope. The customisation effort to make it CEO-appropriate is a one-time investment that is less total work than assembling the equivalent plugin stack in MkDocs.

Customisation for a CEO Audience

Quartz’s default audience is personal knowledge management enthusiasts. Transforming it into a professional business wiki requires changes across five dimensions:

1. Remove “Digital Garden” Signals

Default Element	Action	How
Graph view	Remove or hide on homepage	Delete `Component.Graph()` from `quartz.layout.ts`
”Explorer” label	Rename to “Contents” or “Navigation”	Custom component text or CSS override
Backlinks section	Keep but rename to “Related Pages”	Modify `Backlinks.tsx` component text
Popover previews	Keep — useful for a CEO navigating relationships	No change needed
”Digital garden” in page title/footer	Remove any references	Edit `quartz.config.ts` `pageTitle` and footer component

2. Typography and Colour Scheme

Replace the default palette with professional colours:

// quartz.config.ts
theme: {
  typography: {
    header: "Inter",      // Clean, widely-used sans-serif
    body: "Inter",
    code: "JetBrains Mono",
  },
  colors: {
    lightMode: {
      light: "#FFFFFF",       // Clean white background
      lightgray: "#E5E7EB",   // Subtle borders
      gray: "#9CA3AF",        // Muted secondary text
      darkgray: "#374151",    // Body text
      dark: "#111827",        // Headers
      secondary: "#1D4ED8",   // Professional blue links
      tertiary: "#3B82F6",    // Hover states
      highlight: "#EFF6FF",   // Light blue highlights
      textHighlight: "#FEF3C7" // Warm yellow for highlighted text
    }
  }
}

Replace the sidebar Explorer with a horizontal top navigation bar listing the five wiki sections:

[Logo/Title]  |  Entities  |  Concepts  |  Sources  |  Analysis  |  Decisions  |  [Search]

This requires a custom header component in quartz.layout.ts. The Morrowind Modding Wiki and Brandon Boswell’s site demonstrate this pattern successfully.

4. Landing Page

Replace the default index.md note-style homepage with a structured landing page:

Company logo and wiki title
Brief description of purpose (“Your strategic knowledge base”)
Card grid linking to each section (Entities, Concepts, Sources, Analysis, Decisions)
Recent updates list
Search prominently placed

The Gatekeeper Wiki and Socratica Toolbox provide working examples of card-grid homepages built in Quartz.

5. Labels and Language

Default Term	Business Alternative
Explorer	Contents / Navigation
Backlinks	Related Pages / See Also
Graph View	Relationship Map (if kept)
Tags	Topics / Categories
Created / Modified	Published / Last Updated

Real-World Quartz Deployments

Ten live Quartz sites were evaluated. The most relevant to the business wiki use case:

Site	Type	Customisation	Professional Feel	UX Rating
Brandon Boswell	Creator portfolio/blog	Heavy — custom nav, avatar, category grid, golden accents	High	4.5/5
Morrowind Modding Wiki	Community wiki	Moderate — top nav, custom logo, section hierarchy	High	4/5
Simon Späti Second Brain	Professional knowledge base	Moderate-heavy — coral brand colour, top nav, 1000+ notes	Medium-high	4/5
Gatekeeper Wiki	Game product wiki	Moderate — dark theme, card nav, custom logo	High	3.5/5
Sideny’s 3D Handbook	Technical reference	Light — emoji sidebar, callout boxes, hierarchical structure	Medium	4/5
Quartz Docs	Framework documentation	Default (reference implementation)	Neutral	3.5/5
Jacky Zhao’s Garden	Personal garden	Heavy — hand-drawn art, custom homepage, serif typography	Low (personal)	4/5
Socratica Toolbox	Learning guide	Extreme — grid paper texture, illustrated cards, marquee	Low (playful)	4/5
Aaron Pham	Personal ML notes	Extreme minimal — brutalist, cream background, sparse nav	Low (avant-garde)	3/5
Ellie Huxtable	Developer portfolio	Heavy — monospace, terminal aesthetic, two-column layout	Medium (developer)	3.5/5

Key Patterns from Professional Sites

Replace sidebar Explorer with horizontal top nav — the single most impactful change (used by Brandon Boswell, Morrowind Wiki, Simon Späti, Gatekeeper)
Disable graph view — it signals “digital garden” more than “business documentation” (disabled by 5 of 10 sites)
Add a custom branded homepage with card/tile grid entry points (Gatekeeper, Socratica, Brandon Boswell)
Apply even one branded accent colour — differentiates dramatically from vanilla Quartz (Späti’s coral, Boswell’s gold, Gatekeeper’s cyan)
Add a logo or avatar in the header (Morrowind, Brandon Boswell, Simon Späti)

Risk Assessment and Recommendation

Risks

Risk	Likelihood	Mitigation
Case-sensitive links break wiki navigation	High (if casing is inconsistent)	Apply PR #2327 locally; enforce consistent casing with Obsidian Linter plugin
Solo maintainer abandons project	Low-medium	MIT licence allows forking; v5 community org discussion underway
v5 introduces breaking changes	Medium (12–24 month horizon)	Pin to v4 branch; changes are unlikely to affect content format
CEO cannot troubleshoot build errors	Medium	Pre-configure CI/CD pipeline; document the `npx quartz sync` workflow
MkDocs Material ecosystem disrupted by MkDocs 2.0	Medium	Reduces the “safer alternative” argument for MkDocs

Final Recommendation

Use Quartz for this project. The rationale:

Zero conversion layer — every alternative requires plugins, converters, or pre-processing steps to handle [[wiki links]]. Quartz processes them natively. For a 178-page wiki with extensive cross-linking, this eliminates an entire class of bugs.
Built-in features match requirements — graph view, backlinks, search, TOC, frontmatter, and dark mode all work without additional packages. MkDocs requires 3–4 pip-installable plugins to match this; Docusaurus requires React knowledge.
One-time customisation investment — transforming the default “digital garden” aesthetic into a professional business tool requires CSS/layout work, but this is a one-time cost amortised over the life of the wiki. The alternatives’ ongoing plugin maintenance and conversion pipeline complexity is a recurring cost.
CEO workflow is simple post-setup — edit Markdown in Obsidian, run npx quartz sync. No Python, no React, no conversion scripts.

Invest the customisation effort upfront: professional typography (Inter), brand colour palette, horizontal top nav, card-grid homepage, renamed labels. Budget 2–3 developer-days for this. The Brandon Boswell and Morrowind Modding Wiki sites prove this is achievable and effective.

Sources

All citations are inline throughout the report. Key primary sources:

Pride Intelligence

Contents

Recent

quartz-evaluation