DOCSEARCHbyAlgolia
Submit Docs

Quartz

repository·v5·Indexed 11 days ago

https://github.com/jackyzha0/quartz

A toolset for publishing digital gardens and networked notes as a website. Quartz v5 features a plugin-based architecture with transformers, filters, and emitters, utilizing a unified pipeline to convert Markdown to HTML via Preact and Lightning CSS. It supports SPA-style navigation with custom lifecycle events like 'nav' and 'render', and provides a layered dependency model for community plugins via @quartz-community packages.

Tokens
85.2K
Snippets
312
Records
469
Agent score
89%

What's inside Quartz

  1. Overview of Quartz appearance and publishing features

    v5

    Quartz includes features for site presentation and deployment:

    • Reading Experience: Light/dark mode toggle, reader mode for distraction-free reading, and auto-generated Open Graph social images.
    • Engagement: Support for comments via providers like Giscus or Utterances.
    • Deployment & Distribution: RSS feed generation, SPA (Single-Page Application) routing for fast navigation, Docker support for containerized deployment, and internationalization (i18n) with over 30 supported locales.
    • Privacy: Support for private pages to control what content is published.

  2. Overview of Quartz navigation and discovery features

    v5

    Quartz provides several tools to help users navigate and discover content:

    • Search & Visualization: Full-text search and an interactive graph view of note connections.
    • Contextual Navigation: Backlinks (showing what links to the current page), breadcrumbs, and a table of contents for individual pages.
    • Browsing: A file tree sidebar (Explorer), folder and tag listings, and a list of recently modified notes.
    • Interactive UI: Popover previews for internal links, Andy Matuschak-style stacked pages for tracing connections, and the ability to password-protect individual pages using client-side encryption.

  3. Overview of Quartz content features

    v5

    Quartz supports a wide range of Markdown flavors and advanced content types out of the box. Key content features include:

    • Obsidian Compatibility: Full support for Obsidian-flavored Markdown, including [[wikilinks]] and callout blocks.
    • Advanced Rendering: Support for LaTeX math, Mermaid diagrams, and syntax highlighting for code blocks.
    • Specialized Formats: Support for OxHugo and Roam Research syntax, academic citations, and Obsidian Canvas files (rendered as interactive pages).
    • Data Views: 'Bases' allow you to create database-like views such as tables, cards, and galleries for your notes.

  4. What is the core philosophy of Quartz?

    v5

    Quartz is built on the principle of a digital garden rather than a traditional file cabinet or hierarchical folder structure (like Notion).

    Key concepts include:

    • Rhizomatic Structure: Instead of linear or hierarchical organization, Quartz encourages a web-like, interconnected topology of notes to mirror the non-linear nature of human thought.
    • Sharing as Expression: Quartz is primarily a publishing tool designed to make sharing digital gardens free and simple, facilitating feedback loops with a wider network.
    • Agentic Software: The tool provides opinionated defaults to nudge users toward good results but remains fully under the user's control, allowing for deep customization through its open source nature.

  5. Overview of Quartz Plugin Types

    v5

    Plugins in Quartz v5 are categorized by their role in the build pipeline. Note that these types are not mutually exclusive; a single plugin can fulfill multiple roles.

    • Transformers: Map over content (e.g., parsing frontmatter, syntax highlighting).
    • Filters: Filter content (e.g., removing drafts, handling explicit publishing).
    • Emitters: Reduce over content to generate new files (e.g., RSS feeds, sitemaps, OG images).
    • Page Types: Define how specific categories of pages are rendered (e.g., content notes, tag listings, 404 pages). The PageTypeDispatcher routes pages to these plugins.
    • Bases Views: Custom view renderers for the bases-page plugin's database-like view system (e.g., timeline or kanban views).

  6. Use the ArticleTitle component

    v5
    The ArticleTitle component renders the article's title as an <h1> heading at the top of the page content. It automatically retrieves the title from the page's frontmatter title field, and if that field is missing, it falls back to using the filename as the title.

  7. How hot reloading works in Quartz

    v5
    When running with --serve, Quartz automatically enables --watch and uses a WebSocket connection on the port specified by --wsPort (default 3001). When a file changes, the server notifies the browser via this WebSocket, triggering an automatic page refresh to show the latest content.

  8. Understand Page Frames and Layouts

    v5

    Page frames control the inner HTML structure of each page. While the outer shell (<html>, <head>, <body>, #quartz-root) remains constant to support SPA Routing, the frame determines how layout slots (sidebars, center, footer) are arranged.

    Quartz provides several built-in frames:

    • DefaultFrame: A three-column layout featuring a left sidebar, center column, right sidebar, and footer.
    • FullWidthFrame: A single center column with no sidebars.
    • MinimalFrame: A layout containing only the content and footer, with no sidebars and no header/beforeBody sections.

  9. Configure link resolution strategies

    v5

    Link resolution determines how Quartz interprets internal links in your Markdown files:

    • shortest: Resolves links to the closest matching file name. This is the default for Obsidian and TTRPG templates.
    • absolute: Resolves links relative to the root of your content folder.
    • relative: Resolves links relative to the current file's location.

    Note: When using the Obsidian or TTRPG templates, link resolution is automatically set to shortest and the prompt is skipped.

  10. How Quartz components work

    v5

    While Quartz does not use React, it uses a similar component model. A component is a JavaScript function that takes data (props) and produces HTML as output. In v5, most components are community plugins—standalone repositories that export a QuartzComponent. This decoupling allows for easier maintenance and sharing across the ecosystem.

    import {
  QuartzComponent,
  QuartzComponentConstructor,
  QuartzComponentProps,
} from "@quartz-community/types"

const MyComponent: QuartzComponentConstructor<Options> = (userOpts?: Options) => {
  const Component: QuartzComponent = (props: QuartzComponentProps) => {
    return <p>Hello World</p>
  }
  return Component
}

  11. How StackedPages interactions work

    v5

    The StackedPages plugin changes how users navigate through content:

    • Link Clicking: Opens the target page in a new pane to the right. If maxTabs is reached, the oldest (leftmost) pane is removed.
    • Closing Panes: Users can click the × button in a pane's header to remove it from the stack.
    • Collapsed Spines: When panes overflow the viewport, earlier panes collapse into a thin vertical spine showing the page title. Clicking a spine expands that pane back into focus.
    • History Navigation: The stack state is integrated with browser history via the URL hash, so the browser's back and forward buttons work as expected for the stack trail.

  12. Configure Quartz features via plugins

    v5
    Most features in Quartz are powered by a plugin system. You can enable, disable, or customize these features by modifying the quartz.config.yaml file. This allows you to tailor the content rendering, navigation, and appearance of your site to your specific needs.