Quartz: Turn Markdown Notes Into a Searchable, Linked Digital Garden

You already have the Markdown notes. The problem is that they never leave your local folder: search lives in your editor, references live in your memory, and sharing means copy-paste.

Moving them into a normal blog is not quite right either. A blog assumes a timeline. A digital garden assumes a network. Quartz is built for the second model: publish Markdown notes as a website people can search, traverse, and understand as connected knowledge.

What Quartz Is

Quartz is an open-source static-site generator for digital gardens, personal knowledge bases, and Obsidian-style notes. Its promise is simple: turn Markdown content into a fully functional website.

It is not just another generic blog framework. Its defaults are designed around relationships between notes:

Feature	What it solves
Wikilinks	Link notes with [[Note Name]]
Backlinks	Show which pages reference the current page
Graph View	Render relationships across the knowledge base
Full-text Search	Search content directly on the site
Popover Preview	Preview linked pages on hover
Obsidian Compatibility	Preserve Obsidian-style writing habits
LaTeX / Mermaid / Syntax Highlighting	Support technical notes out of the box

As of May 2026, the Quartz docs show v4.5.2, and the jackyzha0/quartz GitHub repository has about 12.2k stars and 3.8k forks. This is no longer a weekend script. It is a publishing tool used by students, developers, teachers, and note-takers who want their knowledge base on the web.

Where It Wins

Quartz’s advantage is not “it can generate static pages.” Hugo, Astro, and Next.js can all do that. Quartz wins because the knowledge-base features are already there.

It keeps Markdown low-friction. You keep writing plain Markdown. You do not need to turn every note into a CMS entry. The content remains easy to version, search, diff, and process with AI tools.

It understands bidirectional links. A normal static site treats links as navigation. Quartz treats links as structure. Wikilinks, backlinks, and graph view let readers move through concepts instead of only following dates or folders.

It supports publishing in progress. A digital garden is not “write, polish, publish, forget.” You can publish rough notes, add links later, and let the site structure evolve as your thinking evolves.

It is fast by default. Static pages mean no database round trips, cheap hosting, and fast loads. The official docs also emphasize fast page loads and small bundles.

Best Use Cases

Publishing a personal knowledge base. If you already write in Obsidian, Logseq, or plain Markdown, Quartz is a direct path from local notes to a public website.

Research notes and course material. Papers, lectures, experiments, and reading notes are naturally networked. Graphs, backlinks, and previews help readers move between concepts without relying on a linear table of contents.

Product or engineering team wikis. Small teams do not always need a heavy knowledge-base system. Put Markdown in Git, generate a Quartz site, and run review, deployment, and rollback through normal engineering workflows.

AI learning libraries. If you are collecting prompts, model behavior, tool patterns, and failure modes, Quartz is a good fit because it connects concepts, examples, mistakes, and code snippets.

Where It Does Not Fit

Quartz is not a universal content platform.

Do not treat it like WordPress. If you need an admin editor, complex permissions, comment moderation, paywalls, or dynamic forms, Quartz is not the center of gravity. It is closer to a Git-managed public knowledge base.

Do not expect a zero-config branded site. The default theme is useful, but serious brand work still means editing config, layout, and components. You get more freedom than a website builder, and you pay for it with engineering effort.

Be careful with large private knowledge bases. Quartz supports private pages and ignore patterns, but the core model is publishing. Sensitive content should be separated before build time, not patched after output exists.

Decide your filename and linking strategy early. Digital gardens suffer when slugs churn. Short links, folder structure, and tag conventions are worth deciding in the first 20 notes.

Quartz is best when the job is not “I want a blog.” It is “I already have a knowledge network, and I want other people to walk through it.”

Installation

Quartz currently requires Node v22 and npm v10.9.2 or newer. The official quick start is:

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

The create command walks you through initializing your content. After that, you can write Markdown, adjust config, preview locally, and deploy.

Quick Start

These are the files you will touch most:

File	Purpose
content/	Markdown notes
quartz.config.ts	Site title, theme, plugins, parsing rules
quartz.layout.ts	Page layout and component placement
quartz/components/	Custom components
quartz/plugins/	Custom parsing, filtering, and emitting logic

Create a note:

---
title: Context Engineering
tags:
  - ai
  - prompt-engineering
---

Context engineering is not about stuffing more text into a prompt.
It is about deciding what the model needs to see right now.

Related: [[RAG]], [[Function Calling]], [[Agent Memory]]

When this note is published, Quartz resolves the wikilinks into internal links. Referenced pages show backlinks, and the graph view shows the connections.

For local build and preview:

npx quartz build --serve

To generate static output for deployment:

npx quartz build

Configure It Like a Knowledge Base

Quartz’s default config already enables common transformers, filters, and emitters. In quartz.config.ts, you will see a structure like this:

const config = {
  configuration: {
    pageTitle: "My Digital Garden",
    enableSPA: true,
    enablePopovers: true,
    locale: "en-US",
    ignorePatterns: ["private", "templates", ".obsidian"],
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.ObsidianFlavoredMarkdown(),
      Plugin.GitHubFlavoredMarkdown(),
      Plugin.TableOfContents(),
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      Plugin.Latex({ renderEngine: "katex" }),
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.ContentPage(),
      Plugin.FolderPage(),
      Plugin.TagPage(),
      Plugin.ContentIndex({ enableSiteMap: true, enableRSS: true }),
    ],
  },
}

The mental model is simple: parse Markdown into a content graph, filter what should not be published, then emit pages, folder listings, tag pages, RSS, and sitemap output.

Practical Example: Publish AI Notes

Say you have an AI learning folder:

content/
  index.md
  rag.md
  function-calling.md
  agent-memory.md
  prompt-injection.md

Use index.md as the entry point:

---
title: AI Systems Notes
tags:
  - ai
---

Start here:

- [[RAG]] for retrieval-heavy systems
- [[Function Calling]] for tool execution
- [[Agent Memory]] for long-running workflows
- [[Prompt Injection]] for security boundaries

Then cross-link the notes:

---
title: Agent Memory
tags:
  - agents
  - memory
---

Agent memory is useful when a task spans multiple sessions.
It becomes risky when the system stores unverified user input.

Security boundary: [[Prompt Injection]]
Retrieval pattern: [[RAG]]

This is where Quartz becomes useful. Readers do not just land on an article. They can follow the chain from memory to retrieval to security boundaries and understand the system as a network.

How to Design Navigation

The easiest way to weaken a Quartz site is to design it like a normal blog: Home, Blog, About in the top nav, then a giant folder tree on the side. It works, but it leaves most of Quartz unused.

A better model splits navigation into three layers: entry navigation, semantic navigation, and local navigation.

Layer	Job	Good fit
Entry navigation	Show the major areas of the site	Notes, Projects, Topics, About
Semantic navigation	Let readers move through concepts	Wikilinks, backlinks, tags, graph view
Local navigation	Explain the current page structure	Table of contents, folder page, related notes

Keep the top nav light. Its job is to get readers into the right area, not explain the whole knowledge base. Real exploration should happen through links, backlinks, tags, and the graph.

For an AI knowledge base, a useful top-level navigation might look like this:

Top nav item	Purpose
Start Here	Give first-time readers an entry point
Concepts	Core ideas like RAG, agents, prompting, evaluation
Patterns	Reusable systems like retrieval pipelines, tool use, memory design
Notes	Working notes that are public but not fully polished
About	Author, update cadence, and scope

Then make each note part of the network instead of a standalone article:

---
title: Agent Memory
tags:
  - agents
  - memory
status: working-note
---

Agent memory matters when a task spans multiple sessions.

Use it with [[RAG]] when the agent needs external context.
Treat [[Prompt Injection]] as the security boundary.
Compare with [[Context Window]] before adding persistence.

The goal is not a prettier navigation bar. The goal is to reduce the reader’s next-step cost. After finishing a page, they should immediately know where to go next: deeper into a concept, across to a pattern, back to a topic page, or through backlinks into a disagreement.

A practical navigation rule set:

• Keep top navigation under 5 items
• Give every core note at least 3 outgoing links
• Make tag pages behave like topic pages, not tag dumps
• Use Start Here for new readers only, not as the whole directory
• Treat graph view as an exploration aid, not the primary navigation

Quartz navigation is not about exposing every possible doorway. It is about making the next jump obvious at every step.

Common Traps

Designing folders as the whole navigation system. In a digital garden, folders should not carry all structure. Folders give rough grouping. Links carry meaning. If everything depends on the directory tree, Quartz loses its edge.

Publishing pages that behave like isolated blog posts. If every note has a date, title, body, and no outgoing links, Quartz becomes an overbuilt blog engine.

Failing to mark unfinished notes. Rough notes are fine, but mark their status in frontmatter, tags, or body copy. Otherwise readers treat drafts as conclusions.

Assuming every Obsidian plugin will work online. Quartz supports many Obsidian-style patterns, but it is not the full Obsidian runtime. Dynamic content generated by local plugins may not survive publication.

Bottom Line

Quartz’s value is not turning Markdown into web pages. Its value is turning isolated notes into a knowledge network people can explore.

If your content is naturally organized by links, do not start with a blog. Start by letting Quartz publish the network.

GitHub: https://github.com/jackyzha0/quartz
Docs: https://quartz.jzhao.xyz/