### Real-world Example: Quartz Themes Plugin Source: https://quartz.jzhao.xyz/configuration Install the quartz-themes plugin located in a subdirectory of its repository, specifying theme and mode options. ```yaml plugins: - source: name: quartz-themes repo: "https://github.com/saberzero1/quartz-themes.git" subdir: plugin enabled: true options: theme: "tokyo-night" mode: both ``` -------------------------------- ### Basic Quartz Configuration Source: https://quartz.jzhao.xyz/configuration Example of the quartz.config.yaml file showing general page title configuration and plugin setup. ```yaml configuration: pageTitle: "My Site" # ... general configuration plugins: - source: github:quartz-community/some-plugin enabled: true # ... plugin entries ``` -------------------------------- ### Install and Preview Quartz 5 Source: https://quartz.jzhao.xyz/ Clone the Quartz repository, install dependencies, initialize your site, install plugins, and preview it locally. Ensure Node v22 and npm v10.9.2 are installed. ```bash git clone https://github.com/jackyzha0/quartz.git cd quartz npm i npx quartz create npx quartz plugin install --from-config npx quartz build --serve ``` -------------------------------- ### Perform Clean Plugin Installation Source: https://quartz.jzhao.xyz/cli/plugin Installs plugins, skipping existing directories to ensure a fresh setup. Useful for resolving installation issues. ```bash npx quartz plugin install --clean ``` -------------------------------- ### Run Quartz Locally with Docker Source: https://quartz.jzhao.xyz/features/docker-support Use this command to start a Docker container for local preview of your Quartz site. Ensure you have Docker installed and the Quartz image built. ```bash docker run --rm -itp 8080:8080 -p 3001:3001 -v ./content:/usr/src/app/content $(docker build -q .) ``` -------------------------------- ### Preview Installation from Configuration Source: https://quartz.jzhao.xyz/cli/plugin Shows which plugins would be installed or removed based on the `quartz.config.yaml` without applying changes. ```bash npx quartz plugin install --from-config --dry-run ``` -------------------------------- ### Clone and Install Plugin Template Source: https://quartz.jzhao.xyz/advanced/creating-components Use this command to clone the official plugin template and install its dependencies to start building a new component plugin. ```bash git clone https://github.com/quartz-community/plugin-template.git my-component cd my-component npm install ``` -------------------------------- ### Install Plugins from Configuration Source: https://quartz.jzhao.xyz/cli/plugin Synchronizes installed plugins with the `quartz.config.yaml` file. Installs missing plugins and removes unconfigured ones. ```bash npx quartz plugin install --from-config ``` -------------------------------- ### Set Up Quartz 5 for Returning Users Source: https://quartz.jzhao.xyz/ Clone an existing Quartz repository on a new machine, install dependencies, install plugins, and preview the site locally. This is for users who already have a Quartz project. ```bash git clone https://github.com//.git cd npm ci npx quartz plugin install npx quartz build --serve ``` -------------------------------- ### Install Quartz Dependencies Source: https://quartz.jzhao.xyz/getting-started Run this command in your project directory to install the necessary dependencies for Quartz. ```bash npx quartz create ``` -------------------------------- ### Install Project Dependencies Source: https://quartz.jzhao.xyz/getting-started/installation Install the necessary Node.js dependencies for the project. Ensure you have Node.js 22 or later installed. ```bash npm i ``` -------------------------------- ### Install Plugins from Lockfile Source: https://quartz.jzhao.xyz/cli/plugin Installs all plugins defined in the `quartz.lock.json` file. This is the default behavior for ensuring project consistency. ```bash npx quartz plugin install ``` -------------------------------- ### Show All Elements Example Source: https://quartz.jzhao.xyz/features/explorer Example to override the default filter and show all elements in the explorer. ```typescript ExternalPlugin.Explorer({ filterFn: undefined, // apply no filter function, every file and folder will visible }) ``` -------------------------------- ### Quartz Layout Configuration Example Source: https://quartz.jzhao.xyz/layout Example of `quartz.config.yaml` showing how to enable plugins and configure their layout positions and priorities, as well as defining layout groups and page-type specific overrides. ```yaml plugins: - source: github:quartz-community/explorer enabled: true layout: position: left priority: 50 - source: github:quartz-community/graph enabled: true layout: position: right priority: 10 - source: github:quartz-community/search enabled: true layout: position: left priority: 20 - source: github:quartz-community/backlinks enabled: true layout: position: right priority: 30 - source: github:quartz-community/article-title enabled: true layout: position: beforeBody priority: 10 - source: github:quartz-community/content-meta enabled: true layout: position: beforeBody priority: 20 - source: github:quartz-community/tag-list enabled: true layout: position: beforeBody priority: 30 - source: github:quartz-community/footer enabled: true options: links: GitHub: https://github.com/jackyzha0/quartz Discord Community: https://discord.gg/cRFFHYye7t layout: groups: toolbar: direction: row gap: 0.5rem byPageType: content: {} folder: exclude: - reader-mode positions: right: [] tag: exclude: - reader-mode positions: right: [] "404": positions: beforeBody: [] left: [] right: [] ``` -------------------------------- ### Install Backlinks Plugin Source: https://quartz.jzhao.xyz/features/backlinks Use this command to install the backlinks plugin for Quartz. Ensure you have npx installed. ```bash npx quartz plugin add github:quartz-community/backlinks ``` -------------------------------- ### Preview Plugin Installation Changes Source: https://quartz.jzhao.xyz/cli/plugin Simulates the installation or removal of plugins without making any actual changes to the file system. Useful for planning. ```bash npx quartz plugin install --dry-run ``` -------------------------------- ### Install Project Dependencies Source: https://quartz.jzhao.xyz/setting-up-your-github-repository Install project dependencies using npm. For subsequent clones of your own repository, use `npm ci` for a faster, reproducible install from the lockfile. ```bash npm i ``` ```bash npm ci ``` -------------------------------- ### Install Custom Component via CLI Source: https://quartz.jzhao.xyz/advanced/creating-components Users can install custom components from a repository using the Quartz CLI command. ```bash npx quartz plugin add github:your-username/my-component ``` -------------------------------- ### Install Plugins from Configuration Source: https://quartz.jzhao.xyz/advanced/making-plugins Installs all plugins that are referenced in your Quartz configuration but are missing from the lockfile. Use `--dry-run` to preview changes without modifying files. ```bash npx quartz plugin install --from-config ``` ```bash npx quartz plugin install --from-config --dry-run ``` -------------------------------- ### Install Quartz Bases Page Plugin Source: https://quartz.jzhao.xyz/features/bases Use this command to install the Quartz Bases Page plugin. Ensure you have npx available. ```bash npx quartz plugin add github:quartz-community/bases-page ``` -------------------------------- ### List Installed Plugins Source: https://quartz.jzhao.xyz/cli/plugin Lists all plugins currently installed in the project along with their versions. ```bash npx quartz plugin list ``` -------------------------------- ### Install Explorer Plugin Source: https://quartz.jzhao.xyz/features/explorer Install the Explorer community plugin from GitHub using npm. Ensure you use the --legacy-peer-deps flag if necessary. ```bash npm install github:quartz-community/explorer --legacy-peer-deps ``` -------------------------------- ### Install Plugins with Lower Concurrency Source: https://quartz.jzhao.xyz/troubleshooting When `plugin install` hangs or causes Out-Of-Memory errors on low-end hardware, reduce the parallelism. This command installs plugins one at a time. ```bash # Install one plugin at a time (safest, slowest) npx quartz plugin install --latest -c 1 # Two at a time — usually works on 4 GB machines npx quartz plugin install --latest --concurrency 2 ``` -------------------------------- ### StackedPages Plugin Configuration Example Source: https://quartz.jzhao.xyz/plugins/stackedpages Example configuration for the StackedPages plugin in a quartz.config.yaml file. This shows how to enable the plugin and set its options. ```yaml ```yaml - source: github:quartz-community/stacked-pages enabled: true layout: position: afterBody priority: 50 display: all options: maxTabs: 8 mobileBreakpoint: 800 showSpines: true animateTransitions: true ``` ``` -------------------------------- ### Install Plugin via GitHub Source: https://quartz.jzhao.xyz/advanced/making-plugins Command to install a plugin directly from a GitHub repository. This clones the plugin and updates configuration files. ```bash # In your Quartz project npx quartz plugin add github:your-username/my-plugin ``` -------------------------------- ### Quartz CLI Quick Reference Commands Source: https://quartz.jzhao.xyz/cli A table summarizing common Quartz CLI commands, their descriptions, and example usage. ```bash npx quartz create ``` ```bash npx quartz build ``` ```bash npx quartz sync ``` ```bash npx quartz upgrade ``` ```bash npx quartz plugin list ``` ```bash npx quartz tui ``` -------------------------------- ### Install Quartz TUI Plugin Source: https://quartz.jzhao.xyz/cli/tui Run this command to add the TUI plugin to your Quartz project. Ensure you have Bun installed. ```bash npx quartz plugin add github:quartz-community/tui ``` -------------------------------- ### Reproducible Dependency Installation Source: https://quartz.jzhao.xyz/getting-started/installation Use 'npm ci' for faster and more reproducible dependency installation on subsequent clones of your own repository. ```bash npm ci ``` -------------------------------- ### Install Reader Mode Plugin Source: https://quartz.jzhao.xyz/features/reader-mode To install the Reader Mode plugin, use the npx quartz plugin add command with the plugin's source. ```bash npx quartz plugin add github:quartz-community/reader-mode ``` -------------------------------- ### Install Search Plugin Source: https://quartz.jzhao.xyz/plugins/search Command to install the Quartz search plugin using npx. This command adds the plugin from the specified GitHub repository. ```bash npx quartz plugin add github:quartz-community/search ``` -------------------------------- ### Add Plugin from Git Repository Source: https://quartz.jzhao.xyz/cli/plugin Installs a new plugin by cloning it from a specified Git repository URL. ```bash npx quartz plugin add github:username/repo ``` -------------------------------- ### Install Recent Notes Plugin Source: https://quartz.jzhao.xyz/features/recent-notes Install the Recent Notes plugin using npx. This command adds the plugin to your project. ```bash npx quartz plugin add github:quartz-community/recent-notes ``` -------------------------------- ### Footnote Syntax Example Source: https://quartz.jzhao.xyz/features/obsidian-compatibility Demonstrates the syntax for creating footnotes using the GitHubFlavoredMarkdown plugin. ```markdown Here is a sentence with a footnote.[^1] [^1]: This is the footnote content. ``` -------------------------------- ### Install Graph View Plugin Source: https://quartz.jzhao.xyz/features/graph-view Install the Graph View community plugin using npm. Ensure to use legacy peer dependencies if required. ```bash npm install github:quartz-community/graph --legacy-peer-deps ``` -------------------------------- ### Configure Plugin in YAML Source: https://quartz.jzhao.xyz/advanced/making-plugins Example of configuring a plugin in `quartz.config.yaml`, specifying its source and enabling it. ```yaml plugins: - source: github:your-username/my-plugin enabled: true ``` -------------------------------- ### Enable a Plugin Source: https://quartz.jzhao.xyz/cli/plugin Activates a plugin by updating its status in `quartz.config.yaml`. The plugin's files remain installed. ```bash npx quartz plugin enable plugin-name ``` -------------------------------- ### Install Search Plugin Source: https://quartz.jzhao.xyz/features/full-text-search Use this command to add the search plugin to your Quartz project. Ensure you are in your project's root directory. ```bash npx quartz plugin add github:quartz-community/search ``` -------------------------------- ### Install CanvasPage Plugin Source: https://quartz.jzhao.xyz/canvas.canvas Use this command to add the CanvasPage plugin to your Quartz project. ```bash npx quartz plugin add github:quartz-community/canvas-page ``` -------------------------------- ### Recommended CI/CD Pattern for Quartz v5 Source: https://quartz.jzhao.xyz/getting-started/migrating This pattern shows how to cache dependencies and Quartz plugins in a GitHub Actions workflow to optimize build times. It includes steps for installing dependencies, installing Quartz plugins, and building the project. ```yaml - name: Cache dependencies uses: actions/cache@v5 with: path: ~/.npm key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node- - name: Cache Quartz plugins uses: actions/cache@v5 with: path: .quartz/plugins key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }} restore-keys: | ${{ runner.os }}-plugins- - run: npm ci - name: Install Quartz plugins run: npx quartz plugin install - name: Build Quartz run: npx quartz build ``` -------------------------------- ### Configure Component in quartz.config.yaml Source: https://quartz.jzhao.xyz/advanced/creating-components Add installed components to the Quartz configuration file, specifying options, position, and priority. ```yaml plugins: - source: github:your-username/my-component enabled: true options: favouriteNumber: 42 layout: position: left priority: 60 ``` -------------------------------- ### Per-Note Frontmatter Override Example Source: https://quartz.jzhao.xyz/plugins/frontmatter This example demonstrates how to control the frontmatter properties panel on a per-note basis using frontmatter keys. It forces the panel to show and start expanded, overriding global settings. ```yaml --- title: My Note quartz-properties: true quartz-properties-collapse: false --- ``` -------------------------------- ### Tag Syntax Source: https://quartz.jzhao.xyz/features/obsidian-compatibility Provides examples of how tags starting with '#' are parsed and linked, including nested and dashed tags. Pure numeric tags are ignored. ```markdown #tag #nested/tag #tag-with-dashes ``` -------------------------------- ### Cloning and Installing Quartz Plugin Template Source: https://quartz.jzhao.xyz/advanced/making-plugins Steps to create a new Quartz plugin repository using the official template and set up the project locally. ```bash # Use the plugin template to create a new repository on GitHub # Then clone it locally git clone https://github.com/your-username/my-plugin.git cd my-plugin npm install ``` -------------------------------- ### Create Quartz Project for a Blog Source: https://quartz.jzhao.xyz/cli/create Sets up a new Quartz project configured for a blog, enabling recent notes and comments, and initializing with a new content strategy. ```bash npx quartz create --template blog --strategy new --baseUrl myblog.github.io ``` -------------------------------- ### Development Mode with Serve and Watch Source: https://quartz.jzhao.xyz/cli/build Starts a local development server and automatically watches for file changes, rebuilding the site as needed. This is the most common way to preview your site during development. ```bash npx quartz build --serve ``` -------------------------------- ### Remove Installed Plugin Source: https://quartz.jzhao.xyz/cli/plugin Removes a previously installed plugin from the project. ```bash npx quartz plugin remove plugin-name ``` -------------------------------- ### Perform First Sync (Skip Pull) Source: https://quartz.jzhao.xyz/cli/sync Execute this command when setting up a new repository to skip the pull step. ```bash npx quartz sync --no-pull ``` -------------------------------- ### Custom Filter Function Example Source: https://quartz.jzhao.xyz/features/explorer Example of filtering out specific elements by their display name. ```typescript ExternalPlugin.Explorer({ filterFn: (node) => { // set containing names of everything you want to filter out const omit = new Set(["authoring content", "tags", "advanced"]) // can also use node.slug or by anything on node.data // note that node.data is only present for files that exist on disk // (e.g. implicit folder nodes that have no associated index.md) return !omit.has(node.displayName.toLowerCase()) }, }) ``` -------------------------------- ### Plugin CLI Commands for Quartz Source: https://quartz.jzhao.xyz/advanced/architecture Commands to manage community plugins in a Quartz project. Use 'add' to install, 'install --latest' to update, 'install --clean' to restore from lockfile, and 'remove' to uninstall. ```bash npx quartz plugin add github:quartz-community/ ``` ```bash npx quartz plugin install --latest ``` ```bash npx quartz plugin install --clean ``` ```bash npx quartz plugin remove ``` -------------------------------- ### Filter Files by Tag Example Source: https://quartz.jzhao.xyz/features/explorer Example of filtering files based on their tags, excluding those with the 'explorerexclude' tag. ```typescript ExternalPlugin.Explorer({ filterFn: (node) => { // exclude files with the tag "explorerexclude" return node.data?.tags?.includes("explorerexclude") !== true }, }) ``` -------------------------------- ### Custom Map Function Example Source: https://quartz.jzhao.xyz/features/explorer Example of using a map function to convert display names to uppercase. ```typescript ExternalPlugin.Explorer({ mapFn: (node) => { node.displayName = node.displayName.toUpperCase() return node }, }) ``` -------------------------------- ### Sync and Push Site to GitHub Source: https://quartz.jzhao.xyz/setting-up-your-github-repository Commit your content and push all changes to your GitHub repository. For subsequent updates, simply run `npx quartz sync`. ```bash npx quartz sync --no-pull ``` ```bash npx quartz sync ``` -------------------------------- ### Custom Sort Function Example Source: https://quartz.jzhao.xyz/features/explorer Example of providing a custom sort function to the explorer to sort alphabetically. ```typescript ExternalPlugin.Explorer({ sortFn: (a, b) => { return a.displayName.localeCompare(b.displayName) }, }) ``` -------------------------------- ### Add Quartz Plugin Source: https://quartz.jzhao.xyz/troubleshooting Install a specific plugin by its GitHub repository. This is useful when a plugin is referenced in quartz.ts but not installed. ```bash npx quartz plugin add github:quartz-community/plugin-name ``` -------------------------------- ### Basic Site Build Source: https://quartz.jzhao.xyz/cli/build Generates your static site into the default `public` folder. This is the most basic usage of the build command. ```bash npx quartz build ``` -------------------------------- ### Install Specific Plugins to Latest Version Source: https://quartz.jzhao.xyz/cli/plugin Installs or updates specific listed plugins to their latest available versions. ```bash npx quartz plugin install --latest plugin-a plugin-b ``` -------------------------------- ### Create Quartz Project with Obsidian Template Source: https://quartz.jzhao.xyz/cli/create Initializes a Quartz project using the Obsidian template, employing symbolic links for content synchronization, and specifying the source directory of an Obsidian vault. ```bash npx quartz create --template obsidian --strategy symlink --source ~/Documents/MyVault ``` -------------------------------- ### Example: Remove Drafts Filter Plugin Source: https://quartz.jzhao.xyz/advanced/making-plugins An example of a filter plugin that removes content marked as drafts using frontmatter. ```typescript import { QuartzFilterPlugin } from "@quartz-community/types" export const RemoveDrafts: QuartzFilterPlugin<{}> = () => ({ name: "RemoveDrafts", shouldPublish(_ctx, [_tree, vfile]) { // uses frontmatter parsed from transformers const draftFlag: boolean = vfile.data?.frontmatter?.draft ?? false return !draftFlag }, }) ``` -------------------------------- ### Build Plugin Source: https://quartz.jzhao.xyz/advanced/making-plugins Commands to build your plugin. Use `npm run build` or `npx tsup`. ```bash # Build the plugin npm run build # or npx tsup ``` -------------------------------- ### Fetch and Checkout v5 Branch Source: https://quartz.jzhao.xyz/getting-started/migrating Add the official Quartz repository as a remote, fetch the v5 branch, create a local v5 branch, install dependencies, and push it to your repository. ```bash # Add the official Quartz repository as a remote called "upstream" (skip if already set) git remote add upstream https://github.com/jackyzha0/quartz.git # Fetch the v5 branch from the official repository git fetch upstream v5 # Create a local v5 branch from the official one git checkout -b v5 upstream/v5 # Install dependencies npm i # Push v5 to your GitHub repository git push -u origin v5 ``` -------------------------------- ### Inline Math Example Source: https://quartz.jzhao.xyz/features/latex Render inline math by enclosing expressions in single dollar signs ($). For example, `$e^{i\pi} = -1$`. ```markdown `$e^{i\pi} = -1$` produces eiπ=−1 ``` -------------------------------- ### Connect Local Clone to GitHub Repository Source: https://quartz.jzhao.xyz/getting-started/installation Configure your local Quartz clone to point to your new GitHub repository and add the official Quartz repository as an upstream for future upgrades. ```bash # Check current remotes git remote -v # Point origin to your repository git remote set-url origin REMOTE-URL # Add the official Quartz repo as upstream (for future upgrades) git remote add upstream https://github.com/jackyzha0/quartz.git ``` -------------------------------- ### Run Quartz Upgrade Source: https://quartz.jzhao.xyz/cli/upgrade Execute the command to upgrade the Quartz framework to the latest version. ```bash npx quartz upgrade ``` -------------------------------- ### Install Latest Plugin Versions Source: https://quartz.jzhao.xyz/cli/plugin Fetches and installs the latest available versions of plugins from their remote sources, overriding versions specified in the lockfile. ```bash npx quartz plugin install --latest ``` -------------------------------- ### Quartz CLI Help Command Source: https://quartz.jzhao.xyz/cli Display help information for the Quartz CLI and specific commands. Use the --help flag to see all available options. ```bash npx quartz --help npx quartz build --help ``` -------------------------------- ### Add Plugin from Local Directory Source: https://quartz.jzhao.xyz/cli/plugin Installs a plugin from a local file system path, useful for development or air-gapped environments. Local plugins are symlinked. ```bash npx quartz plugin add ./path/to/my-plugin ``` ```bash npx quartz plugin add ../sibling-plugin ``` ```bash npx quartz plugin add /absolute/path/to/plugin ``` -------------------------------- ### Example BibTex Entry Source: https://quartz.jzhao.xyz/features/citations This is an example of an article entry in a BibTex file. It includes essential fields like title, author, year, journal, and URL. ```bibtex @article{templeton2024scaling, title={Scaling Monosemanticity: Extracting Interpretable Features from Claude 3 Sonnet}, author={Templeton, Adly and Conerly, Tom and Marcus, Jonathan and Lindsey, Jack and Bricken, Trenton and Chen, Brian and Pearce, Adam and Citro, Craig and Ameisen, Emmanuel and Jones, Andy and Cunningham, Hoagy and Turner, Nicholas L and McDougall, Callum and MacDiarmid, Monte and Freeman, C. Daniel and Sumers, Theodore R. and Rees, Edward and Batson, Joshua and Jermyn, Adam and Carter, Shan and Olah, Chris and Henighan, Tom}, year={2024}, journal={Transformer Circuits Thread}, url={https://transformer-circuits.pub/2024/scaling-monosemanticity/index.html} } ``` -------------------------------- ### Content Page Emitter Plugin Example Source: https://quartz.jzhao.xyz/advanced/making-plugins A simplified example of a content page emitter plugin that renders every page using Quartz components. It utilizes `renderPage` and `write` utilities. ```typescript import { QuartzEmitterPlugin, FullPageLayout, QuartzComponentProps } from "@quartz-community/types" import { renderPage, canonicalizeServer, pageResources, write } from "@quartz-community/utils" export const ContentPage: QuartzEmitterPlugin = () => { return { name: "ContentPage", getQuartzComponents(ctx) { const { head, header, beforeBody, pageBody, afterBody, left, right, footer } = ctx.cfg.layout return [head, ...header, ...beforeBody, pageBody, ...afterBody, ...left, ...right, footer] }, async emit(ctx, content, resources): Promise { const cfg = ctx.cfg.configuration const fps: FilePath[] = [] const allFiles = content.map((c) => c[1].data) for (const [tree, file] of content) { const slug = canonicalizeServer(file.data.slug!) const externalResources = pageResources(slug, file.data, resources) const componentData: QuartzComponentProps = { fileData: file.data, externalResources, cfg, children: [], tree, allFiles, } const content = renderPage(cfg, slug, componentData, {}, externalResources) const fp = await write({ ctx, content, slug: file.data.slug!, ext: ".html", }) fps.push(fp) } return fps }, } } ``` -------------------------------- ### View Plugin Configuration Source: https://quartz.jzhao.xyz/cli/plugin Displays the current configuration settings for a specified plugin. ```bash npx quartz plugin config plugin-name ``` -------------------------------- ### Explorer Plugin TS Override Example Source: https://quartz.jzhao.xyz/plugins/explorer Example of overriding Explorer plugin behavior using TypeScript in quartz.ts. This snippet demonstrates a custom map function to convert display names to uppercase. ```typescript import * as ExternalPlugin from "./.quartz/plugins" // Must be placed before loadQuartzConfig() ExternalPlugin.Explorer({ mapFn: (node) => { node.displayName = node.displayName.toUpperCase() return node }, }) ```