Get AI summaries of any video or article — Sign up free
How to publish your notes for free with Quartz thumbnail

How to publish your notes for free with Quartz

Nicole van der Hoeven·
5 min read

Based on Nicole van der Hoeven's video on YouTube. If you like this content, support the original creators by watching, liking and subscribing to their content.

TL;DR

Quartz is a free static site generator that converts Markdown into HTML, but it relies on separate tools for note authoring and hosting.

Briefing

Quartz is a free static site generator built to publish Markdown notes from Obsidian (or any Markdown source) without paying for Obsidian Publish or being locked into a single hosted service. The core setup pairs Obsidian for authoring, Quartz for converting Markdown into HTML and generating a navigable site, and GitHub Pages for hosting—turning a local notes vault into a public website with link navigation and graph-style views.

The workflow starts by separating the publishing problem into three parts: creating/editing notes as Markdown, converting Markdown into HTML, and hosting the resulting site on a server. Obsidian Publish handles all three, but it’s paid, can’t be self-hosted, and has performance and customization limitations. Quartz only covers the middle step—static site generation—so users keep their existing note-taking setup while gaining more control over the publishing pipeline.

The guide then lays out a step-by-step build from scratch. First, Quartz is installed by cloning or copying its open-source repository locally, then meeting its minimum Node.js and NPM requirements and running dependency installation. After that, Quartz is initialized with a choice of content setup options (the walkthrough uses an “empty Quartz” start) and a link-resolution mode tailored to Obsidian-style vault links.

Next comes GitHub setup. A new public GitHub repository is created without initializing it, then the local Quartz repository is re-pointed to the new origin remote. Synchronization is performed using Quartz’s sync command so the Quartz project structure appears in GitHub. After that, the local Quartz folder is opened as an Obsidian vault so Markdown content can be created inside the expected structure.

Content authoring is handled in Obsidian using Quartz-compatible conventions. The walkthrough installs Obsidian plugins such as Longform and Templater, then creates a Longform project and a README. It also adds templates for chapters (and optionally scenes) so new notes follow the format Quartz expects—using Templater variables like title and draft status and placing templates in a Templates folder.

Once content exists, changes are pushed to GitHub and previewed locally by running Quartz’s server/preview command. The site is then made publicly accessible by adding a GitHub Actions workflow (deploy.yml) that runs Quartz sync and builds the static output. In GitHub’s Pages settings, the source is set to GitHub Actions, and the resulting site becomes reachable at the standard GitHub Pages URL.

A final optional step supports custom domains. DNS configuration requires an A record pointing to GitHub’s IP addresses, and GitHub Pages settings are updated to use the domain and optionally enforce HTTPS. The walkthrough notes that DNS propagation can be slow and frustrating, so patience is required.

The conclusion frames Quartz as a complement rather than a full replacement: Obsidian Publish remains convenient for most note publishing, while Quartz is used for specific projects where a more controllable static-site workflow is valuable. The guide also credits Quartz’s developer, Jacky Zhao, and thanks a community member for testing static site generators and encouraging the switch.

Cornell Notes

Quartz is a free static site generator designed to publish Markdown notes by converting them into HTML and producing a website structure. It doesn’t replace note-taking tools; it plugs into an existing workflow where Obsidian (or another editor) creates Markdown, Quartz generates the static site, and a hosting provider serves it online. The walkthrough uses GitHub Pages as the host, with GitHub Actions to automate deployment. The setup requires installing Quartz with the right Node.js/NPM versions, initializing a Quartz project, syncing to a GitHub repo, opening the Quartz folder as an Obsidian vault, and creating content using Quartz-compatible templates (via Longform and Templater). A custom domain is optional and involves DNS A records plus GitHub Pages configuration.

Why isn’t Quartz a direct replacement for Obsidian Publish, and what role does it actually play?

Quartz focuses on the middle step of publishing: turning Markdown into HTML via static site generation. Obsidian Publish handles authoring, conversion, and hosting in one paid service, while Quartz leaves authoring to Obsidian (or another editor) and hosting to a separate provider like GitHub Pages. That separation is why Quartz can be free and more customizable, but still requires a hosting setup.

What are the three components involved in publishing Markdown notes online?

First, a tool to create/edit notes and store them as Markdown (Obsidian, a text editor, or an IDE like VS Code). Second, a static site generator that converts Markdown into HTML, which is more portable and standard for websites. Third, a hosting step that serves the generated HTML from a server—either a personal server or a third-party host such as GitHub Pages, Cloudflare, or Netlify.

What does the setup require before Quartz can generate a site?

Quartz must be installed locally by cloning/copying its repository, then installing dependencies with npm after confirming minimum Node.js and NPM versions. After that, Quartz is initialized (the walkthrough chooses “empty Quartz”) and configured for link resolution appropriate to Obsidian vaults. Only then can Quartz sync content and build/preview the generated site.

How does the guide make Quartz content work with Obsidian authoring?

The Quartz folder is opened in Obsidian as a vault so Markdown can be created where Quartz expects it. The walkthrough installs Longform and Templater, creates a Longform project, adds a README, and sets up templates in a Templates folder (including a chapter template using Templater variables like title and draft). This ensures new notes follow the structure Quartz looks for.

How does the site get deployed automatically to GitHub Pages?

A GitHub Actions workflow file (deploy.yml) is added to the forked repository. In GitHub settings, Pages is configured to use GitHub Actions as the source. The workflow runs Quartz sync/build so the generated static output is published, making the site available at the username.github.io URL.

What’s involved in using a custom domain with Quartz on GitHub Pages?

DNS must be configured with an A record pointing to GitHub’s IP addresses so requests route to GitHub’s servers. Then GitHub Pages settings are updated with the custom domain, a DNS check is performed, and HTTPS can be enforced. DNS propagation can take time—often up to an hour or more—so delays are expected.

Review Questions

  1. What publishing step does Quartz handle, and which steps must be handled by other tools in a Quartz-based workflow?
  2. Why do templates and link-resolution settings matter when generating a Quartz site from an Obsidian vault?
  3. What changes are required in GitHub Pages settings to deploy a Quartz-generated site using GitHub Actions?

Key Points

  1. 1

    Quartz is a free static site generator that converts Markdown into HTML, but it relies on separate tools for note authoring and hosting.

  2. 2

    A practical workflow pairs Obsidian for Markdown creation, Quartz for static site generation, and GitHub Pages for hosting.

  3. 3

    Quartz installation includes meeting minimum Node.js and NPM requirements, installing dependencies, and initializing a project with appropriate link-resolution behavior.

  4. 4

    GitHub deployment is automated by adding a GitHub Actions workflow (deploy.yml) and configuring GitHub Pages to use GitHub Actions as the source.

  5. 5

    To make Quartz work smoothly with Obsidian, the Quartz folder should be opened as an Obsidian vault and content should follow Quartz’s expected structure using templates.

  6. 6

    Custom domains require DNS A records pointing to GitHub’s IP addresses and GitHub Pages configuration updates, with DNS propagation delays to expect.

  7. 7

    Quartz is positioned as a complement to Obsidian Publish—use the best tool for each publishing need rather than switching everything at once.

Highlights

Quartz handles only static site generation (Markdown → HTML), so users keep their existing authoring tool and choose their own hosting.
Using GitHub Pages plus a GitHub Actions deploy workflow turns a local Quartz project into a live website at username.github.io.
Obsidian plugins like Longform and Templater help create content in the structure Quartz expects, including chapter templates with draft fields.
Custom domains work through DNS A records to GitHub’s IP addresses and GitHub Pages domain settings, but DNS propagation can be slow.
The approach is intentionally modular: author in Obsidian, generate with Quartz, deploy via GitHub Pages.

Topics

Get summaries like this for any content

Videos, articles, research papers — all summarized by AI and searchable in one place.

Start building your library