%% date:: [[2024-01-22]] parent:: %% # [[Quartz]] [site](https://quartz.jzhao.xyz/), [repo](https://github.com/jackyzha0/quartz) Quartz is an [[Open source|opensource]] [[Static site generator]] that turns [[obsidian-playbook/Using Obsidian/02 Making Notes in Obsidian/Markdown|Markdown]] into a website. It is written in [[NodeJS]], and it was built with [[obsidian-playbook/Using Obsidian/01 First steps with Obsidian/Obsidian|Obsidian]] in mind. ## Features ### Obsidian support Specifically, it supports the following Obsidian-friendly features: - [[Wikilinks]] - Diagrams created using the [[Mermaid library]] - Frontmatter parsing of [[Properties in Obsidian]] - customization of links and [[Backlinks]] to use the absolute, relative, or shortest paths, the way Obsidian does - [[Graph view]] - [[Callouts]] - Markdown highlights (` == like this==`) - [[Comments]] (`%% like this %%) - popover previews just like in Obsidian Other static site generators don't have the focus on Obsidian, so usually take some tweaking to get working with Obsidian, including the formatting of links (Markdown vs [[Wikilinks]]) and path conventions. ### Well-documented The [setup is well-documented](https://quartz.jzhao.xyz/) online, with instructions not just for how to set up Quartz but also how to sync it to [[GitHub]] and how to host the Quartz site on [[GitHub Pages]], [[Netlify]], [[Cloudflare Pages]], and [[Vercel]]. ### Comes with [[Continuous Improvement|CI/CD]] instructions There's also an included `deploy.yml` to build a [[GitHub Actions|GitHub Action]], making it easier to have the static site generation happen on the GitHub servers instead of on your local machine. ### Script for handling Git Quartz bundles up all the [[Git]] commands into a single [[npx]] command: ``` npx quartz sync ``` This command adds changes to staging, commits them, and pushes them to the [[Working with remotes in Git|remote]] repository, making it quite friendly for those not used to Git. ### Fast Quartz is a [[Single Page App]] by default, and loads very quickly and responsively. ### Plugin ecosystem Quartz also comes with a [[Plugin]] framework for transforming content. ![[quartz-plugins.png]] *Image from Quartz documentation* [^quartz] Plugins can be: - *Transformers:* reformatting text (for example, Markdown to [[HTML]]) - *Filters:* removing files based on criteria (such as a property being set in [[YAML]] frontmatter) - *Emitters:* reduce content, creating new output files based on an aggregation of other files ## Usage [[How to publish Obsidian notes with Quartz on GitHub Pages|Here's a full guide for how to publish Obsidian notes with Quartz on GitHub Pages]], including installation and setup, specifically using [[obsidian-playbook/Using Obsidian/01 First steps with Obsidian/Obsidian|Obsidian]] + [[Quartz]] + [[GitHub Pages]]. Below are more general steps. More information is found in the [Quartz docs](https://quartz.jzhao.xyz/). ### Installation Clone the repository: ``` git clone https://github.com/jackyzha0/quartz.git ``` Install [[Node Package Manager|NPM]] dependencies: ``` cd quartz npm i ``` Initialize Quartz: ``` npx quartz create ``` ### Local build To generate the HTML from Markdown and build Quartz locally: ``` npx quartz build --serve ``` By default, the site is accessible at http://localhost:8080. ### Push changes to GitHub You can add, commit, and push to GitHub as normal, but Quartz also includes an NPX command to do that altogether: ``` npx quartz sync ``` [^quartz]: https://quartz.jzhao.xyz/advanced/making-plugins