pkg: bump to 4.1.6

* feat(usability): update functions for search

Signed-off-by: Aaron <29749331+aarnphm@users.noreply.github.com>

* perf: slightly cleaner variables

Signed-off-by: Aaron <29749331+aarnphm@users.noreply.github.com>

---------

Signed-off-by: Aaron <29749331+aarnphm@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -20,12 +20,19 @@ Steps to reproduce the behavior:
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
+**Screenshots and Source**
 If applicable, add screenshots to help explain your problem.
 
+You can help speed up fixing the problem by either
+
+1. providing a simple reproduction
+2. linking to your Quartz repository where the problem can be observed
+
 **Desktop (please complete the following information):**
 
-- Device: [e.g. iPhone6]
+- Quartz Version: [e.g. v4.1.2]
+- `node` Version: [e.g. v18.16]
+- `npm` version: [e.g. v10.1.0]
 - OS: [e.g. iOS]
 - Browser [e.g. chrome, safari]
 

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yaml

@@ -1,6 +1,9 @@
 name: Build and Test
 
 on:
+  pull_request:
+    branches:
+      - v4
   push:
     branches:
       - v4
@@ -40,5 +43,11 @@ jobs:
       - name: Test
         run: npm test
 
-      - name: Ensure Quartz builds
+      - name: Ensure Quartz builds, check bundle info
-        run: npx quartz build
+        run: npx quartz build --bundleInfo
+
+      - name: Create release tag
+        uses: Klemensas/action-autotag@stable
+        with:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          tag_prefix: "v"

.gitignore

@@ -7,3 +7,5 @@ tsconfig.tsbuildinfo
 .obsidian
 .quartz-cache
 private/
+.replit
+replit.nix

Dockerfile

@@ -0,0 +1,11 @@
+FROM node:20-slim as builder
+WORKDIR /usr/src/app
+COPY package.json .
+COPY package-lock.json* .
+RUN npm ci
+
+FROM node:20-slim
+WORKDIR /usr/src/app
+COPY --from=builder /usr/src/app/ /usr/src/app/
+COPY . .
+CMD ["npx", "quartz", "build", "--serve"]

README.md

@@ -5,9 +5,7 @@
 Quartz is a set of tools that helps you publish your [digital garden](https://jzhao.xyz/posts/networked-thought) and notes as a website for free.
 Quartz v4 features a from-the-ground rewrite focusing on end-user extensibility and ease-of-use.
 
-**If you are looking for Quartz v3, you can find it on the [`hugo` branch](https://github.com/jackyzha0/quartz/tree/hugo).**
+🔗 Read the documentation and get started: https://quartz.jzhao.xyz/
-
-🔗 Read the documentation and get started: https://four.quartz.jzhao.xyz/
 
 [Join the Discord Community](https://discord.gg/cRFFHYye7t)
 

docs/advanced/index.md

@@ -0,0 +1,3 @@
+---
+title: "Advanced"
+---

docs/advanced/making plugins.md

@@ -216,22 +216,19 @@ export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
 
 export type QuartzEmitterPluginInstance = {
   name: string
-  emit(
+  emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]>
-    ctx: BuildCtx,
-    content: ProcessedContent[],
-    resources: StaticResources,
-    emitCallback: EmitCallback,
-  ): Promise<FilePath[]>
   getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
 }
 ```
 
-An emitter plugin must define a `name` field an `emit` function and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created.
+An emitter plugin must define a `name` field, an `emit` function, and a `getQuartzComponents` function. `emit` is responsible for looking at all the parsed and filtered content and then appropriately creating files and returning a list of paths to files the plugin created.
 
-Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `emitCallback` if you are creating files that contain text. The `emitCallback` function is the 4th argument of the emit function. It's interface looks something like this:
+Creating new files can be done via regular Node [fs module](https://nodejs.org/api/fs.html) (i.e. `fs.cp` or `fs.writeFile`) or via the `write` function in `quartz/plugins/emitters/helpers.ts` if you are creating files that contain text. `write` has the following signature:
 
 ```ts
-export type EmitCallback = (data: {
+export type WriteOptions = (data: {
+  // the build context
+  ctx: BuildCtx
   // the name of the file to emit (not including the file extension)
   slug: ServerSlug
   // the file extension
@@ -247,7 +244,7 @@ If you are creating an emitter plugin that needs to render components, there are
 
 - Your component should use `getQuartzComponents` to declare a list of `QuartzComponents` that it uses to construct the page. See the page on [[creating components]] for more information.
 - You can use the `renderPage` function defined in `quartz/components/renderPage.tsx` to render Quartz components into HTML.
-- If you need to render an HTML AST to JSX, you can use the `toJsxRuntime` function from `hast-util-to-jsx-runtime` library. An example of this can be found in `quartz/components/pages/Content.tsx`.
+- If you need to render an HTML AST to JSX, you can use the `htmlToJsx` function from `quartz/util/jsx.ts`. An example of this can be found in `quartz/components/pages/Content.tsx`.
 
 For example, the following is a simplified version of the content page plugin that renders every single page.
 

docs/authoring content.md

@@ -2,7 +2,7 @@
 title: Authoring Content
 ---
 
-All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initailized. Any Markdown in this folder will get processed by Quartz.
+All of the content in your Quartz should go in the `/content` folder. The content for the home page of your Quartz lives in `content/index.md`. If you've [[index#🪴 Get Started|setup Quartz]] already, this folder should already be initialized. Any Markdown in this folder will get processed by Quartz.
 
 It is recommended that you use [Obsidian](https://obsidian.md/) as a way to edit and maintain your Quartz. It comes with a nice editor and graphical interface to preview, edit, and link your local files and attachments.
 
@@ -28,21 +28,13 @@ The rest of your content lives here. You can use **Markdown** here :)
 Some common frontmatter fields that are natively supported by Quartz:
 
 - `title`: Title of the page. If it isn't provided, Quartz will use the name of the file as the title.
+- `description`: Description of the page used for link previews.
 - `aliases`: Other names for this note. This is a list of strings.
+- `tags`: Tags for this note.
 - `draft`: Whether to publish the page or not. This is one way to make [[private pages|pages private]] in Quartz.
 - `date`: A string representing the day the note was published. Normally uses `YYYY-MM-DD` format.
 
 ## Syncing your Content
 
-When you're Quartz is at a point you're happy with, you can save your changes to GitHub by doing `npx quartz sync`.
+When your Quartz is at a point you're happy with, you can save your changes to GitHub.
-
+First, make sure you've [[setting up your GitHub repository|already setup your GitHub repository]] and then do `npx quartz sync`.
-> [!hint] Flags and options
-> For full help options, you can run `npx quartz sync --help`.
->
-> Most of these have sensible defaults but you can override them if you have a custom setup:
->
-> - `-d` or `--directory`: the content folder. This is normally just `content`
-> - `-v` or `--verbose`: print out extra logging information
-> - `--commit` or `--no-commit`: whether to make a `git` commit for your changes
-> - `--push` or `--no-push`: whether to push updates to your GitHub fork of Quartz
-> - `--pull` or `--no-pull`: whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing

docs/configuration.md

@@ -31,6 +31,7 @@ This part of the configuration concerns anything that can affect the whole site.
   - This should also include the subpath if you are [[hosting]] on GitHub pages without a custom domain. For example, if my repository is `jackyzha0/quartz`, GitHub pages would deploy to `https://jackyzha0.github.io/quartz` and the `baseUrl` would be `jackyzha0.github.io/quartz`
   - Note that Quartz 4 will avoid using this as much as possible and use relative URLs whenever it can to make sure your site works no matter _where_ you end up actually deploying it.
 - `ignorePatterns`: a list of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that Quartz should ignore and not search through when looking for files inside the `content` folder. See [[private pages]] for more details.
+- `defaultDateType`: whether to use created, modified, or published as the default date to display on pages and page listings.
 - `theme`: configure how the site looks.
   - `typography`: what fonts to use. Any font available on [Google Fonts](https://fonts.google.com/) works here.
     - `header`: Font to use for headers

docs/features/Docker Support.md

@@ -0,0 +1,7 @@
+Quartz comes shipped with a Docker image that will allow you to preview your Quartz locally without installing Node.
+
+You can run the below one-liner to run Quartz in Docker.
+
+```sh
+docker run --rm -itp 8080:8080 $(docker build -q .)
+```

docs/features/Obsidian compatibility.md

@@ -25,7 +25,9 @@ Finally, Quartz also provides `Plugin.CrawlLinks` which allows you to customize
     - `callouts`: whether to enable [[callouts]]. Defaults to `true`
     - `mermaid`: whether to enable [[Mermaid diagrams]]. Defaults to `true`
     - `parseTags`: whether to try and parse tags in the content body. Defaults to `true`
+    - `parseArrows`: whether to try and parse arrows in the content body. Defaults to `true`.
     - `enableInHtmlEmbed`: whether to try and parse Obsidian flavoured markdown in raw HTML. Defaults to `false`
+    - `enableYouTubeEmbed`: whether to enable embedded YouTube videos using external image Markdown syntax. Defaults to `false`
 - Link resolution behaviour:
   - Disabling: remove all instances of `Plugin.CrawlLinks()` from `quartz.config.ts`
   - Changing link resolution preference: set `markdownLinkResolution` to one of `absolute`, `relative` or `shortest`

docs/features/OxHugo compatibility.md

@@ -0,0 +1,39 @@
+---
+tags:
+  - plugin/transformer
+---
+
+[org-roam](https://www.orgroam.com/) is a plain-text personal knowledge management system for [emacs](https://en.wikipedia.org/wiki/Emacs). [ox-hugo](https://github.com/kaushalmodi/ox-hugo) is org exporter backend that exports `org-mode` files to [Hugo](https://gohugo.io/) compatible Markdown.
+
+Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by `Plugin.OxHugoFlavouredMarkdown`. Even though this [[making plugins|plugin]] was written with `ox-hugo` in mind, it should work for any Hugo specific Markdown.
+
+```typescript title="quartz.config.ts"
+plugins: {
+  transformers: [
+    Plugin.FrontMatter({ delims: "+++", language: "toml" }), // if toml frontmatter
+    // ...
+    Plugin.OxHugoFlavouredMarkdown(),
+    Plugin.GitHubFlavoredMarkdown(),
+    // ...
+  ],
+},
+```
+
+## Usage
+
+Quartz by default doesn't understand `org-roam` files as they aren't Markdown. You're responsible for using an external tool like `ox-hugo` to export the `org-roam` files as Markdown content to Quartz and managing the static assets so that they're available in the final output.
+
+## Configuration
+
+- Link resolution
+  - `wikilinks`: Whether to replace `{{ relref }}` with Quartz [[wikilinks]]
+  - `removePredefinedAnchor`: Whether to remove [pre-defined anchor set by ox-hugo](https://ox-hugo.scripter.co/doc/anchors/).
+- Image handling
+  - `replaceFigureWithMdImg`: Whether to replace `<figure/>` with `![]()`
+- Formatting
+  - `removeHugoShortcode`: Whether to remove hugo shortcode syntax (`{{}}`)
+  - `replaceOrgLatex`: Whether to replace org-mode formatting for latex fragments with what `Plugin.Latex` supports.
+
+> [!warning]
+>
+> While you can use `Plugin.OxHugoFlavoredMarkdown` and `Plugin.ObsidianFlavoredMarkdown` together, it's not recommended because it might mutate the file in unexpected ways. Use with caution.

docs/features/RSS Feed.md

@@ -3,3 +3,5 @@ Quartz creates an RSS feed for all the content on your site by generating an `in
 ## Configuration
 
 - Remove RSS feed: set the `enableRSS` field of `Plugin.ContentIndex` in `quartz.config.ts` to be `false`.
+- Change number of entries: set the `rssLimit` field of `Plugin.ContentIndex` to be the desired value. It defaults to latest 10 items.
+- Use rich HTML output in RSS: set `rssFullHtml` field of `Plugin.ContentIndex` to be `true`.

docs/features/breadcrumbs.md

@@ -0,0 +1,36 @@
+---
+title: "Breadcrumbs"
+tags:
+  - component
+---
+
+Breadcrumbs provide a way to navigate a hierarchy of pages within your site using a list of its parent folders.
+
+By default, the element at the very top of your page is the breadcrumb navigation bar (can also be seen at the top on this page!).
+
+## Customization
+
+Most configuration can be done by passing in options to `Component.Breadcrumbs()`.
+
+For example, here's what the default configuration looks like:
+
+```typescript title="quartz.layout.ts"
+Component.Breadcrumbs({
+  spacerSymbol: "❯", // symbol between crumbs
+  rootName: "Home", // name of first/root element
+  resolveFrontmatterTitle: true, // whether to resolve folder names through frontmatter titles
+  hideOnRoot: true, // whether to hide breadcrumbs on root `index.md` page
+  showCurrentPage: true, // whether to display the current page in the breadcrumbs
+})
+```
+
+When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
+
+You can also adjust where the breadcrumbs will be displayed by adjusting the [[layout]] (moving `Component.Breadcrumbs()` up or down)
+
+Want to customize it even more?
+
+- Removing breadcrumbs: delete all usages of `Component.Breadcrumbs()` from `quartz.layout.ts`.
+- Component: `quartz/components/Breadcrumbs.tsx`
+- Style: `quartz/components/styles/breadcrumbs.scss`
+- Script: inline at `quartz/components/Breadcrumbs.tsx`

docs/features/callouts.md

@@ -24,7 +24,24 @@ See [documentation on supported types and syntax here](https://help.obsidian.md
 ## Customization
 
 - Disable callouts: simply pass `callouts: false` to the plugin: `Plugin.ObsidianFlavoredMarkdown({ callouts: false })`
-- Editing icons: `quartz/plugins/transformers/ofm.ts`
+- Editing icons: `quartz/styles/callouts.scss`
+
+### Add custom callouts
+
+By default, custom callouts are handled by applying the `note` style. To make fancy ones, you have to add these lines to `custom.scss`.
+
+```scss title="quartz/styles/custom.scss"
+.callout {
+ &[data-callout="custom"] {
+ --color: #customcolor;
+ --border: #custombordercolor;
+ --bg: #custombg;
+ --callout-icon: url('data:image/svg+xml; utf8, <custom formatted svg>'); //SVG icon code
+}
+```
+
+> [!warning]
+> Don't forget to ensure that the SVG is URL encoded before putting it in the CSS. You can use tools like [this one](https://yoksel.github.io/url-encoder/) to help you do that.
 
 ## Showcase
 
@@ -33,7 +50,7 @@ See [documentation on supported types and syntax here](https://help.obsidian.md
 
 > [!question]+ Can callouts be nested?
 >
-> > [!todo]- Yes!, they can.
+> > [!todo]- Yes!, they can. And collapsed!
 > >
 > > > [!example] You can even use multiple layers of nesting.
 

docs/features/darkmode.md

@@ -12,3 +12,12 @@ Quartz supports darkmode out of the box that respects the user's theme preferenc
 - Component: `quartz/components/Darkmode.tsx`
 - Style: `quartz/components/styles/darkmode.scss`
 - Script: `quartz/components/scripts/darkmode.inline.ts`
+
+You can also listen to the `themechange` event to perform any custom logic when the theme changes.
+
+```js
+document.addEventListener("themechange", (e) => {
+  console.log("Theme changed to " + e.detail.theme) // either "light" or "dark"
+  // your logic here
+})
+```

docs/features/explorer.md

@@ -0,0 +1,306 @@
+---
+title: "Explorer"
+tags:
+  - component
+---
+
+Quartz features an explorer that allows you to navigate all files and folders on your site. It supports nested folders and is highly customizable.
+
+By default, it shows all folders and files on your page. To display the explorer in a different spot, you can edit the [[layout]].
+
+Display names for folders get determined by the `title` frontmatter field in `folder/index.md` (more detail in [[authoring content | Authoring Content]]). If this file does not exist or does not contain frontmatter, the local folder name will be used instead.
+
+> [!info]
+> The explorer uses local storage by default to save the state of your explorer. This is done to ensure a smooth experience when navigating to different pages.
+>
+> To clear/delete the explorer state from local storage, delete the `fileTree` entry (guide on how to delete a key from local storage in chromium based browsers can be found [here](https://docs.devolutions.net/kb/general-knowledge-base/clear-browser-local-storage/clear-chrome-local-storage/)). You can disable this by passing `useSavedState: false` as an argument.
+
+## Customization
+
+Most configuration can be done by passing in options to `Component.Explorer()`.
+
+For example, here's what the default configuration looks like:
+
+```typescript title="quartz.layout.ts"
+Component.Explorer({
+  title: "Explorer", // title of the explorer component
+  folderClickBehavior: "collapse", // what happens when you click a folder ("link" to navigate to folder page on click or "collapse" to collapse folder on click)
+  folderDefaultState: "collapsed", // default state of folders ("collapsed" or "open")
+  useSavedState: true, // whether to use local storage to save "state" (which folders are opened) of explorer
+  // Sort order: folders first, then files. Sort folders and files alphabetically
+  sortFn: (a, b) => {
+    ... // default implementation shown later
+  },
+  filterFn: filterFn: (node) => node.name !== "tags", // filters out 'tags' folder
+  mapFn: undefined,
+  // what order to apply functions in
+  order: ["filter", "map", "sort"],
+})
+```
+
+When passing in your own options, you can omit any or all of these fields if you'd like to keep the default value for that field.
+
+Want to customize it even more?
+
+- Removing table of contents: remove `Component.Explorer()` from `quartz.layout.ts`
+  - (optional): After removing the explorer component, you can move the [[table of contents | Table of Contents]] component back to the `left` part of the layout
+- Changing `sort`, `filter` and `map` behavior: explained in [[#Advanced customization]]
+- Component:
+  - Wrapper (Outer component, generates file tree, etc): `quartz/components/Explorer.tsx`
+  - Explorer node (recursive, either a folder or a file): `quartz/components/ExplorerNode.tsx`
+- Style: `quartz/components/styles/explorer.scss`
+- Script: `quartz/components/scripts/explorer.inline.ts`
+
+## Advanced customization
+
+This component allows you to fully customize all of its behavior. You can pass a custom `sort`, `filter` and `map` function.
+All functions you can pass work with the `FileNode` class, which has the following properties:
+
+```ts title="quartz/components/ExplorerNode.tsx" {2-5}
+export class FileNode {
+  children: FileNode[]  // children of current node
+  name: string  // last part of slug
+  displayName: string // what actually should be displayed in the explorer
+  file: QuartzPluginData | null // set if node is a file, see `QuartzPluginData` for more detail
+  depth: number // depth of current node
+
+  ... // rest of implementation
+}
+```
+
+Every function you can pass is optional. By default, only a `sort` function will be used:
+
+```ts title="Default sort function"
+// Sort order: folders first, then files. Sort folders and files alphabetically
+Component.Explorer({
+  sortFn: (a, b) => {
+    if ((!a.file && !b.file) || (a.file && b.file)) {
+      // sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A
+      // numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10"
+      return a.displayName.localeCompare(b.displayName, undefined, {
+        numeric: true,
+        sensitivity: "base",
+      })
+    }
+    if (a.file && !b.file) {
+      return 1
+    } else {
+      return -1
+    }
+  },
+})
+```
+
+---
+
+You can pass your own functions for `sortFn`, `filterFn` and `mapFn`. All functions will be executed in the order provided by the `order` option (see [[#Customization]]). These functions behave similarly to their `Array.prototype` counterpart, except they modify the entire `FileNode` tree in place instead of returning a new one.
+
+For more information on how to use `sort`, `filter` and `map`, you can check [Array.prototype.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), [Array.prototype.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) and [Array.prototype.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
+
+Type definitions look like this:
+
+```ts
+sortFn: (a: FileNode, b: FileNode) => number
+filterFn: (node: FileNode) => boolean
+mapFn: (node: FileNode) => void
+```
+
+> [!tip]
+> You can check if a `FileNode` is a folder or a file like this:
+>
+> ```ts
+> if (node.file) {
+>   // node is a file
+> } else {
+>   // node is a folder
+> }
+> ```
+
+## Basic examples
+
+These examples show the basic usage of `sort`, `map` and `filter`.
+
+### Use `sort` to put files first
+
+Using this example, the explorer will alphabetically sort everything, but put all **files** above all **folders**.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  sortFn: (a, b) => {
+    if ((!a.file && !b.file) || (a.file && b.file)) {
+      return a.displayName.localeCompare(b.displayName)
+    }
+    if (a.file && !b.file) {
+      return -1
+    } else {
+      return 1
+    }
+  },
+})
+```
+
+### Change display names (`map`)
+
+Using this example, the display names of all `FileNodes` (folders + files) will be converted to full upper case.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  mapFn: (node) => {
+    node.displayName = node.displayName.toUpperCase()
+  },
+})
+```
+
+### Remove list of elements (`filter`)
+
+Using this example, you can remove elements from your explorer by providing an array of folders/files using the `omit` set.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  filterFn: (node) => {
+    // set containing names of everything you want to filter out
+    const omit = new Set(["authoring content", "tags", "hosting"])
+    return !omit.has(node.name.toLowerCase())
+  },
+})
+```
+
+You can customize this by changing the entries of the `omit` set. Simply add all folder or file names you want to remove.
+
+### Show every element in explorer
+
+To override the default filter function that removes the `tags` folder from the explorer, you can set the filter function to `undefined`.
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  filterFn: undefined, // apply no filter function, every file and folder will visible
+})
+```
+
+## Advanced examples
+
+> [!tip]
+> When writing more complicated functions, the `layout` file can start to look very cramped.
+> You can fix this by defining your functions in another file.
+>
+> ```ts title="functions.ts"
+> import { Options } from "./quartz/components/ExplorerNode"
+> export const mapFn: Options["mapFn"] = (node) => {
+>   // implement your function here
+> }
+> export const filterFn: Options["filterFn"] = (node) => {
+>   // implement your function here
+> }
+> export const sortFn: Options["sortFn"] = (a, b) => {
+>   // implement your function here
+> }
+> ```
+>
+> You can then import them like this:
+>
+> ```ts title="quartz.layout.ts"
+> import { mapFn, filterFn, sortFn } from "./functions.ts"
+> Component.Explorer({
+>   mapFn: mapFn,
+>   filterFn: filterFn,
+>   sortFn: sortFn,
+> })
+> ```
+
+### Add emoji prefix
+
+To add emoji prefixes (📁 for folders, 📄 for files), you could use a map function like this:
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  mapFn: (node) => {
+    // dont change name of root node
+    if (node.depth > 0) {
+      // set emoji for file/folder
+      if (node.file) {
+        node.displayName = "📄 " + node.displayName
+      } else {
+        node.displayName = "📁 " + node.displayName
+      }
+    }
+  },
+})
+```
+
+### Putting it all together
+
+In this example, we're going to customize the explorer by using functions from examples above to [[#Add emoji prefix | add emoji prefixes]], [[#remove-list-of-elements-filter| filter out some folders]] and [[#use-sort-to-put-files-first | sort with files above folders]].
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  filterFn: sampleFilterFn,
+  mapFn: sampleMapFn,
+  sortFn: sampleSortFn,
+  order: ["filter", "sort", "map"],
+})
+```
+
+Notice how we customized the `order` array here. This is done because the default order applies the `sort` function last. While this normally works well, it would cause unintended behavior here, since we changed the first characters of all display names. In our example, `sort` would be applied based off the emoji prefix instead of the first _real_ character.
+
+To fix this, we just changed around the order and apply the `sort` function before changing the display names in the `map` function.
+
+### Use `sort` with pre-defined sort order
+
+Here's another example where a map containing file/folder names (as slugs) is used to define the sort order of the explorer in quartz. All files/folders that aren't listed inside of `nameOrderMap` will appear at the top of that folders hierarchy level.
+
+It's also worth mentioning, that the smaller the number set in `nameOrderMap`, the higher up the entry will be in the explorer. Incrementing every folder/file by 100, makes ordering files in their folders a lot easier. Lastly, this example still allows you to use a `mapFn` or frontmatter titles to change display names, as it uses slugs for `nameOrderMap` (which is unaffected by display name changes).
+
+```ts title="quartz.layout.ts"
+Component.Explorer({
+  sortFn: (a, b) => {
+    const nameOrderMap: Record<string, number> = {
+      "poetry-folder": 100,
+      "essay-folder": 200,
+      "research-paper-file": 201,
+      "dinosaur-fossils-file": 300,
+      "other-folder": 400,
+    }
+
+    let orderA = 0
+    let orderB = 0
+
+    if (a.file && a.file.slug) {
+      orderA = nameOrderMap[a.file.slug] || 0
+    } else if (a.name) {
+      orderA = nameOrderMap[a.name] || 0
+    }
+
+    if (b.file && b.file.slug) {
+      orderB = nameOrderMap[b.file.slug] || 0
+    } else if (b.name) {
+      orderB = nameOrderMap[b.name] || 0
+    }
+
+    return orderA - orderB
+  },
+})
+```
+
+For reference, this is how the quartz explorer window would look like with that example:
+
+```
+📖 Poetry Folder
+📑 Essay Folder
+    ⚗️ Research Paper File
+🦴 Dinosaur Fossils File
+🔮 Other Folder
+```
+
+And this is how the file structure would look like:
+
+```
+index.md
+poetry-folder
+    index.md
+essay-folder
+    index.md
+    research-paper-file.md
+dinosaur-fossils-file.md
+other-folder
+    index.md
+```

docs/features/full-text search.md

@@ -6,9 +6,11 @@ tags:
 
 Full-text search in Quartz is powered by [Flexsearch](https://github.com/nextapps-de/flexsearch). It's fast enough to return search results in under 10ms for Quartzs as large as half a million words.
 
-It can be opened by either clicking on the search bar or pressing ⌘+K. The top 5 search results are shown on each query. Matching subterms are highlighted and the most relevant 30 words are excerpted. Clicking on a search result will navigate to that page.
+It can be opened by either clicking on the search bar or pressing `⌘`/`ctrl` + `K`. The top 5 search results are shown on each query. Matching subterms are highlighted and the most relevant 30 words are excerpted. Clicking on a search result will navigate to that page.
 
-This component is also keyboard accessible: Tab and Shift+Tab will cycle forward and backward through search results and Enter will navigate to the highlighted result (first result by default).
+To search content by tags, you can either press `⌘`/`ctrl` + `shift` + `K` or start your query with `#` (e.g. `#components`).
+
+This component is also keyboard accessible: Tab and Shift+Tab will cycle forward and backward through search results and Enter will navigate to the highlighted result (first result by default). You are also able to navigate search results using `ArrowUp` and `ArrowDown`.
 
 > [!info]
 > Search requires the `ContentIndex` emitter plugin to be present in the [[configuration]].
@@ -17,7 +19,7 @@ This component is also keyboard accessible: Tab and Shift+Tab will cycle forward
 
 By default, it indexes every page on the site with **Markdown syntax removed**. This means link URLs for instance are not indexed.
 
-It properly tokenizes Chinese, Korean, and Japenese characters and constructs separate indexes for the title and content, weighing title matches above content matches.
+It properly tokenizes Chinese, Korean, and Japenese characters and constructs separate indexes for the title, content and tags, weighing title matches above content matches.
 
 ## Customization
 
@@ -25,4 +27,4 @@ It properly tokenizes Chinese, Korean, and Japenese characters and constructs se
 - Component: `quartz/components/Search.tsx`
 - Style: `quartz/components/styles/search.scss`
 - Script: `quartz/components/scripts/search.inline.ts`
-  - You can edit `contextWindowWords` or `numSearchResults` to suit your needs
+  - You can edit `contextWindowWords`, `numSearchResults` or `numTagResults` to suit your needs

docs/features/graph view.md

@@ -34,6 +34,8 @@ Component.Graph({
     linkDistance: 30, // how long should the links be by default?
     fontSize: 0.6, // what size should the node labels be?
     opacityScale: 1, // how quickly do we fade out the labels when zooming out?
+    removeTags: [], // what tags to remove from the graph
+    showTags: true, // whether to show tags in the graph
   },
   globalGraph: {
     drag: true,
@@ -45,6 +47,8 @@ Component.Graph({
     linkDistance: 30,
     fontSize: 0.6,
     opacityScale: 1,
+    removeTags: [], // what tags to remove from the graph
+    showTags: true, // whether to show tags in the graph
   },
 })
 ```

docs/features/private pages.md

@@ -8,13 +8,21 @@ There may be some notes you want to avoid publishing as a website. Quartz suppor
 
 ## Filter Plugins
 
-[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the `Plugin.RemoveDrafts` plugin which filters out any note that has `drafts: true` in the frontmatter.
+[[making plugins#Filters|Filter plugins]] are plugins that filter out content based off of certain criteria. By default, Quartz uses the `Plugin.RemoveDrafts` plugin which filters out any note that has `draft: true` in the frontmatter.
 
 If you'd like to only publish a select number of notes, you can instead use `Plugin.ExplicitPublish` which will filter out all notes except for any that have `publish: true` in the frontmatter.
 
-## `ignoreFiles`
+> [!warning]
+> Regardless of the filter plugin used, **all non-markdown files will be emitted and available publically in the final build.** This includes files such as images, voice recordings, PDFs, etc. One way to prevent this and still be able to embed local images is to create a folder specifically for public media and add the following two patterns to the ignorePatterns array.
+>
+> `"!(PublicMedia)**/!(*.md)", "!(*.md)"`
 
-This is a field in `quartz.config.ts` under the main [[configuration]] which allows you to specify a list of patterns to effectively exclude from parsing all together. Any valid [glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) pattern works here.
+## `ignorePatterns`
+
+This is a field in `quartz.config.ts` under the main [[configuration]] which allows you to specify a list of patterns to effectively exclude from parsing all together. Any valid [fast-glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) pattern works here.
+
+> [!note]
+> Bash's glob syntax is slightly different from fast-glob's and using bash's syntax may lead to unexpected results.
 
 Common examples include:
 
@@ -24,4 +32,4 @@ Common examples include:
 - `**/private`: exclude any files or folders named `private` at any level of nesting
 
 > [!warning]
-> Marking something as private via either a plugin or through the `ignoreFiles` pattern will only prevent a page from being included in the final built site. If your GitHub repository is public, also be sure to include an ignore for those in the `.gitignore` of your Quartz. See the `git` [documentation](https://git-scm.com/docs/gitignore#_pattern_format) for more information.
+> Marking something as private via either a plugin or through the `ignorePatterns` pattern will only prevent a page from being included in the final built site. If your GitHub repository is public, also be sure to include an ignore for those in the `.gitignore` of your Quartz. See the `git` [documentation](https://git-scm.com/docs/gitignore#_pattern_format) for more information.

docs/features/table of contents.md

@@ -8,6 +8,7 @@ tags:
 Quartz can automatically generate a table of contents from a list of headings on each page. It will also show you your current scroll position on the site by marking headings you've scrolled through with a different colour.
 
 By default, it will show all headers from H1 (`# Title`) all the way to H3 (`### Title`) and will only show the table of contents if there is more than 1 header on the page.
+You can also hide the table of contents on a page by adding `enableToc: false` to the frontmatter for that page.
 
 > [!info]
 > This feature requires both `Plugin.TableOfContents` in your `quartz.config.ts` and `Component.TableOfContents` in your `quartz.layout.ts` to function correctly.
@@ -17,6 +18,7 @@ By default, it will show all headers from H1 (`# Title`) all the way to H3 (`###
 - Removing table of contents: remove all instances of `Plugin.TableOfContents()` from `quartz.config.ts`. and `Component.TableOfContents()` from `quartz.layout.ts`
 - Changing the max depth: pass in a parameter to `Plugin.TableOfContents({ maxDepth: 4 })`
 - Changing the minimum number of entries in the Table of Contents before it renders: pass in a parameter to `Plugin.TableOfContents({ minEntries: 3 })`
+- Collapse the table of content by default: pass in a parameter to `Plugin.TableOfContents({ collapseByDefault: true })`
 - Component: `quartz/components/TableOfContents.tsx`
 - Style:
   - Modern (default): `quartz/components/styles/toc.scss`

docs/features/upcoming features.md

@@ -4,15 +4,14 @@ draft: true
 
 ## high priority backlog
 
+- static dead link detection
 - block links: https://help.obsidian.md/Linking+notes+and+files/Internal+links#Link+to+a+block+in+a+note
 - note/header/block transcludes: https://help.obsidian.md/Linking+notes+and+files/Embedding+files
-- static dead link detection
 - docker support
 
 ## misc backlog
 
 - breadcrumbs component
-- filetree component
 - cursor chat extension
 - https://giscus.app/ extension
 - sidenotes? https://github.com/capnfabs/paperesque

docs/features/wikilinks.md

@@ -10,9 +10,15 @@ This is enabled as a part of [[Obsidian compatibility]] and can be configured an
 
 ## Syntax
 
-- `[[Path to file]]`: produces a link to `Path to file` with the text `Path to file`
+- `[[Path to file]]`: produces a link to `Path to file.md` (or `Path-to-file.md`) with the text `Path to file`
-- `[[Path to file | Here's the title override]]`: produces a link to `Path to file` with the text `Here's the title override`
+- `[[Path to file | Here's the title override]]`: produces a link to `Path to file.md` with the text `Here's the title override`
-- `[[Path to file#Anchor]]`: produces a link to the anchor `Anchor` in the file `Path to file`
+- `[[Path to file#Anchor]]`: produces a link to the anchor `Anchor` in the file `Path to file.md`
+- `[[Path to file#^block-ref]]`: produces a link to the specific block `block-ref` in the file `Path to file.md`
 
-> [!warning]
+### Embeds
-> Currently, Quartz does not support block references or note embed syntax.
+
+- `![[Path to image]]`: embeds an image into the page
+- `![[Path to image|100x145]]`: embeds an image into the page with dimensions 100px by 145px
+- `![[Path to file]]`: transclude an entire page
+- `![[Path to file#Anchor]]`: transclude everything under the header `Anchor`
+- `![[Path to file#^b15695]]`: transclude block with ID `^b15695`

docs/hosting.md

@@ -4,7 +4,10 @@ title: Hosting
 
 Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!).
 
-However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with either GitHub Pages or Cloudflare pages but any service that allows you to deploy static HTML should work as well (e.g. Netlify, Replit, etc.)
+However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with common hosting providers but any service that allows you to deploy static HTML should work as well.
+
+> [!warning]
+> The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, [[setting up your GitHub repository|make sure you do so]].
 
 > [!hint]
 > Some Quartz features (like [[RSS Feed]] and sitemap generation) require `baseUrl` to be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying!
@@ -26,9 +29,10 @@ Press "Save and deploy" and Cloudflare should have a deployed version of your si
 
 To add a custom domain, check out [Cloudflare's documentation](https://developers.cloudflare.com/pages/platform/custom-domains/).
 
-## GitHub Pages
+> [!warning]
+> Cloudflare Pages only allows shallow `git` clones so if you rely on `git` for timestamps, it is recommended you either add dates to your frontmatter (see [[authoring content#Syntax]]) or use another hosting provider.
 
-Like Quartz 3, you can deploy the site generated by Quartz 4 via GitHub Pages.
+## GitHub Pages
 
 In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`.
 
@@ -90,6 +94,9 @@ Then:
 >
 > You can do this by going to your Settings page on your GitHub fork and going to the Environments tab and pressing the trash icon. The GitHub action will recreate the environment for you correctly the next time you sync your Quartz.
 
+> [!info]
+> Quartz generates files in the format of `file.html` instead of `file/index.html` which means the trailing slashes for _non-folder paths_ are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you (e.g. you are migrating from Quartz 3), consider using [[#Cloudflare Pages]].
+
 ### Custom Domain
 
 Here's how to add a custom domain to your GitHub pages deployment.
@@ -113,3 +120,111 @@ See the [GitHub documentation](https://docs.github.com/en/pages/configuring-a-cu
 > There could be many different reasons why your changes aren't showing up but the most likely reason is that you forgot to push your changes to GitHub.
 >
 > Make sure you save your changes to Git and sync it to GitHub by doing `npx quartz sync`. This will also make sure to pull any updates you may have made from other devices so you have them locally.
+
+## Vercel
+
+### Fix URLs
+
+Before deploying to Vercel, a `vercel.json` file is required at the root of the project directory. It needs to contain the following configuration so that URLs don't require the `.html` extension:
+
+```json title="vercel.json"
+{
+  "cleanUrls": true
+}
+```
+
+### Deploy to Vercel
+
+1. Log in to the [Vercel Dashboard](https://vercel.com/dashboard) and click "Add New..." > Project
+2. Import the Git repository containing your Quartz project.
+3. Give the project a name (lowercase characters and hyphens only)
+4. Check that these configuration options are set:
+
+| Configuration option                      | Value              |
+| ----------------------------------------- | ------------------ |
+| Framework Preset                          | `Other`            |
+| Root Directory                            | `./`               |
+| Build and Output Settings > Build Command | `npx quartz build` |
+
+5. Press Deploy. Once it's live, you'll have 2 `*.vercel.app` URLs to view the page.
+
+### Custom Domain
+
+> [!note]
+> If there is something already hosted on the domain, these steps will not work without replacing the previous content. As a workaround, you could use Next.js rewrites or use the next section to create a subdomain.
+
+1. Update the `baseUrl` in `quartz.config.js` if necessary.
+2. Go to the [Domains - Dashboard](https://vercel.com/dashboard/domains) page in Vercel.
+3. Connect the domain to Vercel
+4. Press "Add" to connect a custom domain to Vercel.
+5. Select your Quartz repository and press Continue.
+6. Enter the domain you want to connect it to.
+7. Follow the instructions to update your DNS records until you see "Valid Configuration"
+
+### Use a Subdomain
+
+Using `docs.example.com` is an example of a subdomain. They're a simple way of connecting multiple deployments to one domain.
+
+1. Update the `baseUrl` in `quartz.config.js` if necessary.
+2. Ensure your domain has been added to the [Domains - Dashboard](https://vercel.com/dashboard/domains) page in Vercel.
+3. Go to the [Vercel Dashboard](https://vercel.com/dashboard) and select your Quartz project.
+4. Go to the Settings tab and then click Domains in the sidebar
+5. Enter your subdomain into the field and press Add
+
+## Netlify
+
+1. Log in to the [Netlify dashboard](https://app.netlify.com/) and click "Add new site".
+2. Select your Git provider and repository containing your Quartz project.
+3. Under "Build command", enter `npx quartz build`.
+4. Under "Publish directory", enter `public`.
+5. Press Deploy. Once it's live, you'll have a `*.netlify.app` URL to view the page.
+6. To add a custom domain, check "Domain management" in the left sidebar, just like with Vercel.
+
+## GitLab Pages
+
+In your local Quartz, create a new file `.gitlab-ci.yaml`.
+
+```yaml title=".gitlab-ci.yaml"
+stages:
+  - build
+  - deploy
+
+variables:
+  NODE_VERSION: "18.14"
+
+build:
+  stage: build
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "v4"'
+  before_script:
+    - apt-get update -q && apt-get install -y nodejs npm
+    - npm install -g n
+    - n $NODE_VERSION
+    - hash -r
+    - npm ci
+  script:
+    - npx quartz build
+  artifacts:
+    paths:
+      - public
+  cache:
+    paths:
+      - ~/.npm/
+    key: "${CI_COMMIT_REF_SLUG}-node-${CI_COMMIT_REF_NAME}"
+  tags:
+    - docker
+
+pages:
+  stage: deploy
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "v4"'
+  script:
+    - echo "Deploying to GitLab Pages..."
+  artifacts:
+    paths:
+      - public
+```
+
+When `.gitlab-ci.yaml` is committed, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy > Pages` in the sidebar.
+
+By default, the page is private and only visible when logged in to a GitLab account with access to the repository but can be opened in the settings under `Deploy` -> `Pages`.

docs/index.md

@@ -2,36 +2,36 @@
 title: Welcome to Quartz 4
 ---
 
-Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, wikis, and [digital gardens](https://jzhao.xyz/posts/networked-thought/) to the web.
+Quartz is a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites. Thousands of students, developers, and teachers are [[showcase|already using Quartz]] to publish personal notes, websites, and [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web.
 
 ## 🪴 Get Started
 
-Quartz requires **at least [Node](https://nodejs.org/) v18.14** to function correctly. Ensure you have this installed on your machine before continuing.
+Quartz requires **at least [Node](https://nodejs.org/) v18.14** and `npm` v9.3.1 to function correctly. Ensure you have this installed on your machine before continuing.
 
 Then, in your terminal of choice, enter the following commands line by line:
 
 ```shell
 git clone https://github.com/jackyzha0/quartz.git
 cd quartz
-git checkout v4
 npm i
 npx quartz create
 ```
 
 This will guide you through initializing your Quartz with content. Once you've done so, see how to:
 
-1. [[authoring content|Author content]] in Quartz
+1. [[authoring content|Writing content]] in Quartz
 2. [[configuration|Configure]] Quartz's behaviour
 3. Change Quartz's [[layout]]
 4. [[build|Build and preview]] Quartz
-5. [[hosting|Host]] Quartz online
+5. Sync your changes with [[setting up your GitHub repository|GitHub]]
+6. [[hosting|Host]] Quartz online
 
-> [!info]
+If you prefer instructions in a video format you can try following Nicole van der Hoeven's
-> Coming from Quartz 3? See the [[migrating from Quartz 3|migration guide]] for the differences between Quartz 3 and Quartz 4 and how to migrate.
+[video guide on how to set up Quartz!](https://www.youtube.com/watch?v=6s6DT1yN4dw&t=227s)
 
 ## 🔧 Features
 
-- [[Obsidian compatibility]], [[full-text search]], [[graph view]], [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and [many more](./features) right out of the box
+- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], [[Docker Support]], and [many more](./features) right out of the box
 - Hot-reload for both configuration and content
 - Simple JSX layouts and [[creating components|page components]]
 - [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes

docs/layout.md

@@ -30,7 +30,7 @@ These correspond to following parts of the page:
 
 Quartz **components**, like plugins, can take in additional properties as configuration options. If you're familiar with React terminology, you can think of them as Higher-order Components.
 
-See [a list of all the components](./tags/component) for all available components along with their configuration options. You can also checkout the guide on [[creating components]] if you're interested in further customizing the behaviour of Quartz.
+See [a list of all the components](component.md) for all available components along with their configuration options. You can also checkout the guide on [[creating components]] if you're interested in further customizing the behaviour of Quartz.
 
 ### Style
 

docs/philosophy.md

@@ -8,7 +8,9 @@ title: Philosophy of Quartz
 >
 > _(The Garden and the Stream)_
 
-The problem with the file cabinet is that it focuses on efficiency of access and interoperability rather than generativity and creativity. Thinking is not linear, nor is it hierarchical. In fact, not many things are linear or hierarchical at all. Then why is it that most tools and thinking strategies assume a nice chronological or hierarchical order for my thought processes? The ideal tool for thought for me would embrace the messiness of my mind, and organically help insights emerge from chaos instead of forcing an artificial order. A rhizomatic, not arboresecent, form of note taking.
+The problem with the file cabinet is that it focuses on efficiency of access and interoperability rather than generativity and creativity. Thinking is not linear, nor is it hierarchical. In fact, not many things are linear or hierarchical at all. Then why is it that most tools and thinking strategies assume a nice chronological or hierarchical order for my thought processes?
+
+The ideal tool for thought for me would embrace the messiness of my mind, and organically help insights emerge from chaos instead of forcing an artificial order. A rhizomatic, not arboresecent, form of note taking.
 
 My goal with a digital garden is not purely as an organizing system and information store (though it works nicely for that). I want my digital garden to be a playground for new ways ideas can connect together. As a result, existing formal organizing systems like Zettelkasten or the hierarchical folder structures of Notion don’t work well for me. There is way too much upfront friction that by the time I’ve thought about how to organize my thought into folders categories, I’ve lost it.
 
@@ -20,9 +22,26 @@ Quartz embraces the inherent rhizomatic and web-like nature of our thinking and
 
 The goal of digital gardening should be to tap into your network’s collective intelligence to create constructive feedback loops. If done well, I have a shareable representation of my thoughts that I can send out into the world and people can respond. Even for my most half-baked thoughts, this helps me create a feedback cycle to strengthen and fully flesh out that idea.
 
-Quartz is designed first and foremost as a tool for publishing [digital gardens](https://jzhao.xyz/posts/networked-thought/) to the web. To me, digital gardening is not just passive knowledge collection. It’s a form of expression and sharing.
+Quartz is designed first and foremost as a tool for publishing [digital gardens](https://jzhao.xyz/posts/networked-thought) to the web. To me, digital gardening is not just passive knowledge collection. It’s a form of expression and sharing.
 
 > “[One] who works with the door open gets all kinds of interruptions, but [they] also occasionally gets clues as to what the world is and what might be important.”
 > — Richard Hamming
 
-**The goal of Quartz is to make sharing your digital garden free and simple.** At its core, Quartz is designed to be easy to use enough for non-technical people to get going but also powerful enough that senior developers can tweak it to work how they'd like it to work.
+**The goal of Quartz is to make sharing your digital garden free and simple.**
+
+---
+
+## A garden should be your own
+
+At its core, Quartz is designed to be easy to use enough for non-technical people to get going but also powerful enough that senior developers can tweak it to work how they'd like it to work.
+
+1. If you like the default configuration of Quartz and just want to change the content, the only thing that you need to change is the contents of the `content` folder.
+2. If you'd like to make basic configuration tweaks but don't want to edit source code, one can tweak the plugins and components in `quartz.config.ts` and `quartz.layout.ts` in a guided manner to their liking.
+3. If you'd like to tweak the actual source code of the underlying plugins, components, or even build process, Quartz purposefully ships its full source code to the end user to allow customization at this level too.
+
+Most software either confines you to either
+
+1. Makes it easy to tweak content but not the presentation
+2. Gives you too many knobs to tune the presentation without good opinionated defaults
+
+**Quartz should feel powerful but ultimately be an intuitive tool fully within your control.** It should be a piece of [agentic software](https://jzhao.xyz/posts/agentic-computing). Ultimately, it should have the right affordances to nudge users towards good defaults but never dictate what the 'correct' way of using it is.

docs/setting up your GitHub repository.md

@@ -0,0 +1,48 @@
+---
+title: Setting up your GitHub repository
+---
+
+First, make sure you have Quartz [[index#🪴 Get Started|cloned and setup locally]].
+
+Then, create a new repository on GitHub.com. Do **not** initialize the new repository with `README`, license, or `gitignore` files.
+
+![[github-init-repo-options.png]]
+
+At the top of your repository on GitHub.com's Quick Setup page, click the clipboard to copy the remote repository URL.
+
+![[github-quick-setup.png]]
+
+In your terminal of choice, navigate to the root of your Quartz folder. Then, run the following commands, replacing `REMOTE-URL` with the URL you just copied from the previous step.
+
+```bash
+# list all the repositories that are tracked
+git remote -v
+
+# if the origin doesn't match your own repository, set your repository as the origin
+git remote set-url origin REMOTE-URL
+
+# if you don't have upstream as a remote, add it so updates work
+git remote add upstream https://github.com/jackyzha0/quartz.git
+```
+
+Then, you can sync the content to upload it to your repository. This is a helper command that will do the initial push of your content to your repository.
+
+```bash
+npx quartz sync --no-pull
+```
+
+> [!warning]- `fatal: --[no-]autostash option is only valid with --rebase`
+> You may have an outdated version of `git`. Updating `git` should fix this issue.
+
+In future updates, you can simply run `npx quartz sync` every time you want to push updates to your repository.
+
+> [!hint] Flags and options
+> For full help options, you can run `npx quartz sync --help`.
+>
+> Most of these have sensible defaults but you can override them if you have a custom setup:
+>
+> - `-d` or `--directory`: the content folder. This is normally just `content`
+> - `-v` or `--verbose`: print out extra logging information
+> - `--commit` or `--no-commit`: whether to make a `git` commit for your changes
+> - `--push` or `--no-push`: whether to push updates to your GitHub fork of Quartz
+> - `--pull` or `--no-pull`: whether to try and pull in any updates from your GitHub fork (i.e. from other devices) before pushing

docs/showcase.md

@@ -6,15 +6,24 @@ Want to see what Quartz can do? Here are some cool community gardens:
 
 - [Quartz Documentation (this site!)](https://quartz.jzhao.xyz/)
 - [Jacky Zhao's Garden](https://jzhao.xyz/)
+- [Socratica Toolbox](https://toolbox.socratica.info/)
+- [oldwinter の数字花园](https://garden.oldwinter.top/)
+- [Aaron Pham's Garden](https://aarnphm.xyz/)
+- [The Quantum Garden](https://quantumgardener.blog/)
+- [Abhijeet's Math Wiki](https://abhmul.github.io/quartz/Math-Wiki/)
+- [Matt Dunn's Second Brain](https://mattdunn.info/)
+- [Pelayo Arbues' Notes](https://pelayoarbues.github.io/)
+- [Vince Imbat's Talahardin](https://vinceimbat.com/)
+- [🧠🌳 Chad's Mind Garden](https://www.chadly.net/)
+- [Pedro MC Fernandes's Topo da Mente](https://www.pmcf.xyz/topo-da-mente/)
+- [Mau Camargo's Notkesto](https://notes.camargomau.com/)
+- [Caicai's Novels](https://imoko.cc/blog/caicai/)
+- [🌊 Collapsed Wave](https://collapsedwave.com/)
+- [Sideny's 3D Artist's Handbook](https://sidney-eliot.github.io/3d-artists-handbook/)
+- [Mike's AI Garden 🤖🪴](https://mwalton.me/)
 - [Brandon Boswell's Garden](https://brandonkboswell.com)
 - [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/)
-- [AWAGMI Intern Notes](https://notes.awagmi.xyz/)
-- [Course notes for Information Technology Advanced Theory](https://a2itnotes.github.io/quartz/)
 - [Data Dictionary 🧠](https://glossary.airbyte.com/)
 - [sspaeti.com's Second Brain](https://brain.sspaeti.com/)
-- [oldwinterの数字花园](https://garden.oldwinter.top/)
-- [Abhijeet's Math Wiki](https://abhmul.github.io/quartz/Math-Wiki/)
-- [Mike's AI Garden 🤖🪴](https://mwalton.me/)
-- [Matt Dunn's Second Brain](https://mattdunn.info/)
 
-If you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/v4/content/showcase.md)!
+If you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/v4/docs/showcase.md)!

globals.d.ts

@@ -4,7 +4,7 @@ export declare global {
       type: K,
       listener: (this: Document, ev: CustomEventMap[K]) => void,
     ): void
-    dispatchEvent<K extends keyof CustomEventMap>(ev: CustomEventMap[K]): void
+    dispatchEvent<K extends keyof CustomEventMap>(ev: CustomEventMap[K] | UIEvent): void
   }
   interface Window {
     spaNavigate(url: URL, isBack: boolean = false)

index.d.ts

@@ -6,6 +6,7 @@ declare module "*.scss" {
 // dom custom event
 interface CustomEventMap {
   nav: CustomEvent<{ url: FullSlug }>
+  themechange: CustomEvent<{ theme: "light" | "dark" }>
 }
 
 declare const fetchData: Promise<ContentIndex>

package.json

@@ -2,7 +2,7 @@
   "name": "@jackyzha0/quartz",
   "description": "🌱 publish your digital garden and notes as a website",
   "private": true,
-  "version": "4.0.8",
+  "version": "4.1.6",
   "type": "module",
   "author": "jackyzha0 <j.zhao2k19@gmail.com>",
   "license": "MIT",
@@ -12,12 +12,14 @@
     "url": "https://github.com/jackyzha0/quartz.git"
   },
   "scripts": {
+    "docs": "npx quartz build --serve -d docs",
     "check": "tsc --noEmit && npx prettier . --check",
     "format": "npx prettier . --write",
     "test": "tsx ./quartz/util/path.test.ts",
     "profile": "0x -D prof ./quartz/bootstrap-cli.mjs build --concurrency=1"
   },
   "engines": {
+    "npm": ">=9.3.1",
     "node": ">=18.14"
   },
   "keywords": [
@@ -32,74 +34,75 @@
     "quartz": "./quartz/bootstrap-cli.mjs"
   },
   "dependencies": {
-    "@clack/prompts": "^0.6.3",
+    "@clack/prompts": "^0.7.0",
-    "@floating-ui/dom": "^1.4.0",
+    "@floating-ui/dom": "^1.6.1",
-    "@napi-rs/simple-git": "^0.1.8",
+    "@napi-rs/simple-git": "0.1.14",
     "async-mutex": "^0.4.0",
-    "chalk": "^4.1.2",
+    "chalk": "^5.3.0",
     "chokidar": "^3.5.3",
     "cli-spinner": "^0.2.10",
     "d3": "^7.8.5",
-    "esbuild-sass-plugin": "^2.9.0",
+    "esbuild-sass-plugin": "^2.16.0",
-    "flexsearch": "0.7.21",
+    "flexsearch": "0.7.43",
     "github-slugger": "^2.0.0",
-    "globby": "^13.1.4",
+    "globby": "^14.0.0",
     "gray-matter": "^4.0.3",
-    "hast-util-to-html": "^8.0.4",
+    "hast-util-to-html": "^9.0.0",
-    "hast-util-to-jsx-runtime": "^1.2.0",
+    "hast-util-to-jsx-runtime": "^2.3.0",
-    "hast-util-to-string": "^2.0.0",
+    "hast-util-to-string": "^3.0.0",
     "is-absolute-url": "^4.0.1",
     "js-yaml": "^4.1.0",
-    "lightningcss": "^1.21.5",
+    "lightningcss": "^1.23.0",
-    "mdast-util-find-and-replace": "^2.2.2",
+    "mdast-util-find-and-replace": "^3.0.1",
-    "mdast-util-to-hast": "^12.3.0",
+    "mdast-util-to-hast": "^13.0.2",
-    "mdast-util-to-string": "^3.2.0",
+    "mdast-util-to-string": "^4.0.0",
     "micromorph": "^0.4.5",
-    "plausible-tracker": "^0.3.8",
+    "preact": "^10.19.3",
-    "preact": "^10.14.1",
+    "preact-render-to-string": "^6.3.1",
-    "preact-render-to-string": "^6.0.3",
+    "pretty-bytes": "^6.1.1",
-    "pretty-bytes": "^6.1.0",
     "pretty-time": "^1.1.0",
     "reading-time": "^1.5.0",
-    "rehype-autolink-headings": "^6.1.1",
+    "rehype-autolink-headings": "^7.1.0",
-    "rehype-katex": "^6.0.3",
+    "rehype-katex": "^7.0.0",
-    "rehype-mathjax": "^4.0.3",
+    "rehype-mathjax": "^6.0.0",
-    "rehype-pretty-code": "^0.10.0",
+    "rehype-pretty-code": "^0.12.6",
-    "rehype-raw": "^6.1.1",
+    "rehype-raw": "^7.0.0",
-    "rehype-slug": "^5.1.0",
+    "rehype-slug": "^6.0.0",
-    "remark": "^14.0.2",
+    "remark": "^15.0.1",
-    "remark-frontmatter": "^4.0.1",
+    "remark-breaks": "^4.0.0",
-    "remark-gfm": "^3.0.1",
+    "remark-frontmatter": "^5.0.0",
-    "remark-math": "^5.1.1",
+    "remark-gfm": "^4.0.0",
-    "remark-parse": "^10.0.1",
+    "remark-math": "^6.0.0",
-    "remark-rehype": "^10.1.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.0",
     "remark-smartypants": "^2.0.0",
-    "rimraf": "^5.0.1",
+    "rfdc": "^1.3.1",
+    "rimraf": "^5.0.5",
     "serve-handler": "^6.1.5",
+    "shikiji": "^0.10.2",
     "source-map-support": "^0.5.21",
-    "to-vfile": "^7.2.4",
+    "to-vfile": "^8.0.0",
-    "unified": "^10.1.2",
+    "toml": "^3.0.0",
-    "unist-util-visit": "^4.1.2",
+    "unified": "^11.0.4",
-    "vfile": "^5.3.7",
+    "unist-util-visit": "^5.0.0",
-    "workerpool": "^6.4.0",
+    "vfile": "^6.0.1",
-    "ws": "^8.13.0",
+    "workerpool": "^9.1.0",
+    "ws": "^8.15.1",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@types/cli-spinner": "^0.2.1",
+    "@types/cli-spinner": "^0.2.3",
-    "@types/d3": "^7.4.0",
+    "@types/d3": "^7.4.3",
-    "@types/flexsearch": "^0.7.3",
+    "@types/hast": "^3.0.3",
-    "@types/hast": "^2.3.4",
+    "@types/js-yaml": "^4.0.9",
-    "@types/js-yaml": "^4.0.5",
+    "@types/node": "^20.11.11",
-    "@types/node": "^20.1.2",
+    "@types/pretty-time": "^1.1.5",
-    "@types/pretty-time": "^1.1.2",
+    "@types/source-map-support": "^0.5.10",
-    "@types/source-map-support": "^0.5.6",
+    "@types/ws": "^8.5.10",
-    "@types/workerpool": "^6.4.0",
+    "@types/yargs": "^17.0.32",
-    "@types/ws": "^8.5.5",
+    "esbuild": "^0.19.9",
-    "@types/yargs": "^17.0.24",
+    "prettier": "^3.2.4",
-    "esbuild": "^0.18.11",
+    "tsx": "^4.7.0",
-    "prettier": "^3.0.0",
+    "typescript": "^5.3.3"
-    "tsx": "^3.12.7",
-    "typescript": "^5.0.4"
   }
 }

quartz.config.ts

@@ -10,7 +10,8 @@ const config: QuartzConfig = {
       provider: "plausible",
     },
     baseUrl: "quartz.jzhao.xyz",
-    ignorePatterns: ["private", "templates"],
+    ignorePatterns: ["private", "templates", ".obsidian"],
+    defaultDateType: "created",
     theme: {
       typography: {
         header: "Schibsted Grotesk",
@@ -46,13 +47,15 @@ const config: QuartzConfig = {
       Plugin.FrontMatter(),
       Plugin.TableOfContents(),
       Plugin.CreatedModifiedDate({
-        priority: ["frontmatter", "filesystem"], // you can add 'git' here for last modified from Git but this makes the build slower
+        // you can add 'git' here for last modified from Git
+        // if you do rely on git for dates, ensure defaultDateType is 'modified'
+        priority: ["frontmatter", "filesystem"],
       }),
+      Plugin.Latex({ renderEngine: "katex" }),
       Plugin.SyntaxHighlighting(),
       Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
       Plugin.GitHubFlavoredMarkdown(),
       Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
-      Plugin.Latex({ renderEngine: "katex" }),
       Plugin.Description(),
     ],
     filters: [Plugin.RemoveDrafts()],
@@ -68,6 +71,7 @@ const config: QuartzConfig = {
       }),
       Plugin.Assets(),
       Plugin.Static(),
+      Plugin.NotFoundPage(),
     ],
   },
 }

quartz.layout.ts

@@ -15,25 +15,35 @@ export const sharedPageComponents: SharedLayout = {
 
 // components for pages that display a single page (e.g. a single note)
 export const defaultContentPageLayout: PageLayout = {
-  beforeBody: [Component.ArticleTitle(), Component.ContentMeta(), Component.TagList()],
+  beforeBody: [
+    Component.Breadcrumbs(),
+    Component.ArticleTitle(),
+    Component.ContentMeta(),
+    Component.TagList(),
+  ],
   left: [
     Component.PageTitle(),
     Component.MobileOnly(Component.Spacer()),
     Component.Search(),
     Component.Darkmode(),
-    Component.DesktopOnly(Component.TableOfContents()),
+    Component.DesktopOnly(Component.Explorer()),
+  ],
+  right: [
+    Component.Graph(),
+    Component.DesktopOnly(Component.TableOfContents()),
+    Component.Backlinks(),
   ],
-  right: [Component.Graph(), Component.Backlinks()],
 }
 
 // components for pages that display lists of pages  (e.g. tags or folders)
 export const defaultListPageLayout: PageLayout = {
-  beforeBody: [Component.ArticleTitle()],
+  beforeBody: [Component.Breadcrumbs(), Component.ArticleTitle(), Component.ContentMeta()],
   left: [
     Component.PageTitle(),
     Component.MobileOnly(Component.Spacer()),
     Component.Search(),
     Component.Darkmode(),
+    Component.DesktopOnly(Component.Explorer()),
   ],
   right: [],
 }

quartz/bootstrap-cli.mjs

@@ -1,537 +1,39 @@
 #!/usr/bin/env node
-import { promises, readFileSync } from "fs"
 import yargs from "yargs"
-import path from "path"
 import { hideBin } from "yargs/helpers"
-import esbuild from "esbuild"
+import {
-import chalk from "chalk"
+  handleBuild,
-import { sassPlugin } from "esbuild-sass-plugin"
+  handleCreate,
-import fs from "fs"
+  handleUpdate,
-import { intro, isCancel, outro, select, text } from "@clack/prompts"
+  handleRestore,
-import { rimraf } from "rimraf"
+  handleSync,
-import chokidar from "chokidar"
+} from "./cli/handlers.js"
-import prettyBytes from "pretty-bytes"
+import { CommonArgv, BuildArgv, CreateArgv, SyncArgv } from "./cli/args.js"
-import { execSync, spawnSync } from "child_process"
+import { version } from "./cli/constants.js"
-import http from "http"
-import serveHandler from "serve-handler"
-import { WebSocketServer } from "ws"
-import { randomUUID } from "crypto"
-import { Mutex } from "async-mutex"
-
-const ORIGIN_NAME = "origin"
-const UPSTREAM_NAME = "upstream"
-const QUARTZ_SOURCE_BRANCH = "v4"
-const cwd = process.cwd()
-const cacheDir = path.join(cwd, ".quartz-cache")
-const cacheFile = "./.quartz-cache/transpiled-build.mjs"
-const fp = "./quartz/build.ts"
-const { version } = JSON.parse(readFileSync("./package.json").toString())
-const contentCacheFolder = path.join(cacheDir, "content-cache")
-
-const CommonArgv = {
-  directory: {
-    string: true,
-    alias: ["d"],
-    default: "content",
-    describe: "directory to look for content files",
-  },
-  verbose: {
-    boolean: true,
-    alias: ["v"],
-    default: false,
-    describe: "print out extra logging information",
-  },
-}
-
-const SyncArgv = {
-  ...CommonArgv,
-  commit: {
-    boolean: true,
-    default: true,
-    describe: "create a git commit for your unsaved changes",
-  },
-  push: {
-    boolean: true,
-    default: true,
-    describe: "push updates to your Quartz fork",
-  },
-  pull: {
-    boolean: true,
-    default: true,
-    describe: "pull updates from your Quartz fork",
-  },
-}
-
-const BuildArgv = {
-  ...CommonArgv,
-  output: {
-    string: true,
-    alias: ["o"],
-    default: "public",
-    describe: "output folder for files",
-  },
-  serve: {
-    boolean: true,
-    default: false,
-    describe: "run a local server to live-preview your Quartz",
-  },
-  baseDir: {
-    string: true,
-    default: "",
-    describe: "base path to serve your local server on",
-  },
-  port: {
-    number: true,
-    default: 8080,
-    describe: "port to serve Quartz on",
-  },
-  bundleInfo: {
-    boolean: true,
-    default: false,
-    describe: "show detailed bundle information",
-  },
-  concurrency: {
-    number: true,
-    describe: "how many threads to use to parse notes",
-  },
-}
-
-function escapePath(fp) {
-  return fp
-    .replace(/\\ /g, " ") // unescape spaces
-    .replace(/^".*"$/, "$1")
-    .replace(/^'.*"$/, "$1")
-    .trim()
-}
-
-function exitIfCancel(val) {
-  if (isCancel(val)) {
-    outro(chalk.red("Exiting"))
-    process.exit(0)
-  } else {
-    return val
-  }
-}
-
-async function stashContentFolder(contentFolder) {
-  await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
-  await fs.promises.cp(contentFolder, contentCacheFolder, {
-    force: true,
-    recursive: true,
-    verbatimSymlinks: true,
-    preserveTimestamps: true,
-  })
-  await fs.promises.rm(contentFolder, { force: true, recursive: true })
-}
-
-async function popContentFolder(contentFolder) {
-  await fs.promises.rm(contentFolder, { force: true, recursive: true })
-  await fs.promises.cp(contentCacheFolder, contentFolder, {
-    force: true,
-    recursive: true,
-    verbatimSymlinks: true,
-    preserveTimestamps: true,
-  })
-  await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
-}
-
-function gitPull(origin, branch) {
-  const flags = ["--no-rebase", "--autostash", "-s", "recursive", "-X", "ours", "--no-edit"]
-  const out = spawnSync("git", ["pull", ...flags, origin, branch], { stdio: "inherit" })
-  if (out.stderr) {
-    throw new Error(`Error while pulling updates: ${out.stderr}`)
-  }
-}
 
 yargs(hideBin(process.argv))
   .scriptName("quartz")
   .version(version)
   .usage("$0 <cmd> [args]")
-  .command("create", "Initialize Quartz", CommonArgv, async (argv) => {
+  .command("create", "Initialize Quartz", CreateArgv, async (argv) => {
-    console.log()
+    await handleCreate(argv)
-    intro(chalk.bgGreen.black(` Quartz v${version} `))
-    const contentFolder = path.join(cwd, argv.directory)
-    const setupStrategy = exitIfCancel(
-      await select({
-        message: `Choose how to initialize the content in \`${contentFolder}\``,
-        options: [
-          { value: "new", label: "Empty Quartz" },
-          { value: "copy", label: "Copy an existing folder", hint: "overwrites `content`" },
-          {
-            value: "symlink",
-            label: "Symlink an existing folder",
-            hint: "don't select this unless you know what you are doing!",
-          },
-          { value: "keep", label: "Keep the existing files" },
-        ],
-      }),
-    )
-
-    async function rmContentFolder() {
-      const contentStat = await fs.promises.lstat(contentFolder)
-      if (contentStat.isSymbolicLink()) {
-        await fs.promises.unlink(contentFolder)
-      } else {
-        await rimraf(contentFolder)
-      }
-    }
-
-    if (setupStrategy === "copy" || setupStrategy === "symlink") {
-      const originalFolder = escapePath(
-        exitIfCancel(
-          await text({
-            message: "Enter the full path to existing content folder",
-            placeholder:
-              "On most terminal emulators, you can drag and drop a folder into the window and it will paste the full path",
-            validate(fp) {
-              const fullPath = escapePath(fp)
-              if (!fs.existsSync(fullPath)) {
-                return "The given path doesn't exist"
-              } else if (!fs.lstatSync(fullPath).isDirectory()) {
-                return "The given path is not a folder"
-              }
-            },
-          }),
-        ),
-      )
-
-      await rmContentFolder()
-      if (setupStrategy === "copy") {
-        await fs.promises.cp(originalFolder, contentFolder, {
-          recursive: true,
-          preserveTimestamps: true,
-        })
-      } else if (setupStrategy === "symlink") {
-        await fs.promises.symlink(originalFolder, contentFolder, "dir")
-      }
-    } else if (setupStrategy === "new") {
-      await rmContentFolder()
-      await fs.promises.mkdir(contentFolder)
-      await fs.promises.writeFile(
-        path.join(contentFolder, "index.md"),
-        `---
-title: Welcome to Quartz
----
-
-This is a blank Quartz installation.
-See the [documentation](https://quartz.jzhao.xyz) for how to get started.
-`,
-      )
-    }
-
-    // get a prefered link resolution strategy
-    const linkResolutionStrategy = exitIfCancel(
-      await select({
-        message: `Choose how Quartz should resolve links in your content. You can change this later in \`quartz.config.ts\`.`,
-        options: [
-          {
-            value: "absolute",
-            label: "Treat links as absolute path",
-            hint: "for content made for Quartz 3 and Hugo",
-          },
-          {
-            value: "shortest",
-            label: "Treat links as shortest path",
-            hint: "for most Obsidian vaults",
-          },
-          {
-            value: "relative",
-            label: "Treat links as relative paths",
-            hint: "for just normal Markdown files",
-          },
-        ],
-      }),
-    )
-
-    // now, do config changes
-    const configFilePath = path.join(cwd, "quartz.config.ts")
-    let configContent = await fs.promises.readFile(configFilePath, { encoding: "utf-8" })
-    configContent = configContent.replace(
-      /markdownLinkResolution: '(.+)'/,
-      `markdownLinkResolution: '${linkResolutionStrategy}'`,
-    )
-    await fs.promises.writeFile(configFilePath, configContent)
-
-    outro(`You're all set! Not sure what to do next? Try:
-   • Customizing Quartz a bit more by editing \`quartz.config.ts\`
-   • Running \`npx quartz build --serve\` to preview your Quartz locally
-   • Hosting your Quartz online (see: https://quartz.jzhao.xyz/setup/hosting)
-`)
   })
   .command("update", "Get the latest Quartz updates", CommonArgv, async (argv) => {
-    const contentFolder = path.join(cwd, argv.directory)
+    await handleUpdate(argv)
-    console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
-    console.log("Backing up your content")
-    execSync(
-      `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`,
-    )
-    await stashContentFolder(contentFolder)
-    console.log(
-      "Pulling updates... you may need to resolve some `git` conflicts if you've made changes to components or plugins.",
-    )
-    gitPull(UPSTREAM_NAME, QUARTZ_SOURCE_BRANCH)
-    await popContentFolder(contentFolder)
-    console.log("Ensuring dependencies are up to date")
-    spawnSync("npm", ["i"], { stdio: "inherit" })
-    console.log(chalk.green("Done!"))
   })
   .command(
     "restore",
     "Try to restore your content folder from the cache",
     CommonArgv,
     async (argv) => {
-      const contentFolder = path.join(cwd, argv.directory)
+      await handleRestore(argv)
-      await popContentFolder(contentFolder)
     },
   )
   .command("sync", "Sync your Quartz to and from GitHub.", SyncArgv, async (argv) => {
-    const contentFolder = path.join(cwd, argv.directory)
+    await handleSync(argv)
-    console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
-    console.log("Backing up your content")
-
-    if (argv.commit) {
-      const contentStat = await fs.promises.lstat(contentFolder)
-      if (contentStat.isSymbolicLink()) {
-        const linkTarg = await fs.promises.readlink(contentFolder)
-        console.log(chalk.yellow("Detected symlink, trying to dereference before committing"))
-
-        // stash symlink file
-        await stashContentFolder(contentFolder)
-
-        // follow symlink and copy content
-        await fs.promises.cp(linkTarg, contentFolder, {
-          recursive: true,
-          preserveTimestamps: true,
-        })
-      }
-
-      const currentTimestamp = new Date().toLocaleString("en-US", {
-        dateStyle: "medium",
-        timeStyle: "short",
-      })
-      spawnSync("git", ["add", "."], { stdio: "inherit" })
-      spawnSync("git", ["commit", "-m", `Quartz sync: ${currentTimestamp}`], { stdio: "inherit" })
-
-      if (contentStat.isSymbolicLink()) {
-        // put symlink back
-        await popContentFolder(contentFolder)
-      }
-    }
-
-    await stashContentFolder(contentFolder)
-
-    if (argv.pull) {
-      console.log(
-        "Pulling updates from your repository. You may need to resolve some `git` conflicts if you've made changes to components or plugins.",
-      )
-      gitPull(ORIGIN_NAME, QUARTZ_SOURCE_BRANCH)
-    }
-
-    await popContentFolder(contentFolder)
-    if (argv.push) {
-      console.log("Pushing your changes")
-      spawnSync("git", ["push", "-f", ORIGIN_NAME, QUARTZ_SOURCE_BRANCH], { stdio: "inherit" })
-    }
-
-    console.log(chalk.green("Done!"))
   })
   .command("build", "Build Quartz into a bundle of static HTML files", BuildArgv, async (argv) => {
-    console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
+    await handleBuild(argv)
-    const ctx = await esbuild.context({
-      entryPoints: [fp],
-      outfile: path.join("quartz", cacheFile),
-      bundle: true,
-      keepNames: true,
-      minifyWhitespace: true,
-      minifySyntax: true,
-      platform: "node",
-      format: "esm",
-      jsx: "automatic",
-      jsxImportSource: "preact",
-      packages: "external",
-      metafile: true,
-      sourcemap: true,
-      sourcesContent: false,
-      plugins: [
-        sassPlugin({
-          type: "css-text",
-          cssImports: true,
-        }),
-        {
-          name: "inline-script-loader",
-          setup(build) {
-            build.onLoad({ filter: /\.inline\.(ts|js)$/ }, async (args) => {
-              let text = await promises.readFile(args.path, "utf8")
-
-              // remove default exports that we manually inserted
-              text = text.replace("export default", "")
-              text = text.replace("export", "")
-
-              const sourcefile = path.relative(path.resolve("."), args.path)
-              const resolveDir = path.dirname(sourcefile)
-              const transpiled = await esbuild.build({
-                stdin: {
-                  contents: text,
-                  loader: "ts",
-                  resolveDir,
-                  sourcefile,
-                },
-                write: false,
-                bundle: true,
-                platform: "browser",
-                format: "esm",
-              })
-              const rawMod = transpiled.outputFiles[0].text
-              return {
-                contents: rawMod,
-                loader: "text",
-              }
-            })
-          },
-        },
-      ],
-    })
-
-    const buildMutex = new Mutex()
-    const timeoutIds = new Set()
-    const build = async (clientRefresh) => {
-      await buildMutex.acquire()
-      const result = await ctx.rebuild().catch((err) => {
-        console.error(`${chalk.red("Couldn't parse Quartz configuration:")} ${fp}`)
-        console.log(`Reason: ${chalk.grey(err)}`)
-        process.exit(1)
-      })
-
-      if (argv.bundleInfo) {
-        const outputFileName = "quartz/.quartz-cache/transpiled-build.mjs"
-        const meta = result.metafile.outputs[outputFileName]
-        console.log(
-          `Successfully transpiled ${Object.keys(meta.inputs).length} files (${prettyBytes(
-            meta.bytes,
-          )})`,
-        )
-        console.log(await esbuild.analyzeMetafile(result.metafile, { color: true }))
-      }
-
-      // bypass module cache
-      // https://github.com/nodejs/modules/issues/307
-      const { default: buildQuartz } = await import(cacheFile + `?update=${randomUUID()}`)
-      await buildQuartz(argv, clientRefresh)
-      clientRefresh()
-      buildMutex.release()
-    }
-
-    const rebuild = (clientRefresh) => {
-      timeoutIds.forEach((id) => clearTimeout(id))
-      timeoutIds.add(setTimeout(() => build(clientRefresh), 250))
-    }
-
-    if (argv.serve) {
-      const wss = new WebSocketServer({ port: 3001 })
-      const connections = []
-      wss.on("connection", (ws) => connections.push(ws))
-      const clientRefresh = () => connections.forEach((conn) => conn.send("rebuild"))
-
-      if (argv.baseDir !== "" && !argv.baseDir.startsWith("/")) {
-        argv.baseDir = "/" + argv.baseDir
-      }
-
-      await build(clientRefresh)
-      const server = http.createServer(async (req, res) => {
-        if (argv.baseDir && !req.url?.startsWith(argv.baseDir)) {
-          console.log(
-            chalk.red(
-              `[404] ${req.url} (warning: link outside of site, this is likely a Quartz bug)`,
-            ),
-          )
-          res.writeHead(404)
-          res.end()
-          return
-        }
-
-        // strip baseDir prefix
-        req.url = req.url?.slice(argv.baseDir.length)
-
-        const serve = async () => {
-          await serveHandler(req, res, {
-            public: argv.output,
-            directoryListing: false,
-          })
-          const status = res.statusCode
-          const statusString =
-            status >= 200 && status < 300 ? chalk.green(`[${status}]`) : chalk.red(`[${status}]`)
-          console.log(statusString + chalk.grey(` ${argv.baseDir}${req.url}`))
-        }
-
-        const redirect = (newFp) => {
-          newFp = argv.baseDir + newFp
-          res.writeHead(302, {
-            Location: newFp,
-          })
-          console.log(chalk.yellow("[302]") + chalk.grey(` ${argv.baseDir}${req.url} -> ${newFp}`))
-          res.end()
-        }
-
-        let fp = req.url?.split("?")[0] ?? "/"
-
-        // handle redirects
-        if (fp.endsWith("/")) {
-          // /trailing/
-          // does /trailing/index.html exist? if so, serve it
-          const indexFp = path.posix.join(fp, "index.html")
-          if (fs.existsSync(path.posix.join(argv.output, indexFp))) {
-            req.url = fp
-            return serve()
-          }
-
-          // does /trailing.html exist? if so, redirect to /trailing
-          let base = fp.slice(0, -1)
-          if (path.extname(base) === "") {
-            base += ".html"
-          }
-          if (fs.existsSync(path.posix.join(argv.output, base))) {
-            return redirect(fp.slice(0, -1))
-          }
-        } else {
-          // /regular
-          // does /regular.html exist? if so, serve it
-          let base = fp
-          if (path.extname(base) === "") {
-            base += ".html"
-          }
-          if (fs.existsSync(path.posix.join(argv.output, base))) {
-            req.url = fp
-            return serve()
-          }
-
-          // does /regular/index.html exist? if so, redirect to /regular/
-          let indexFp = path.posix.join(fp, "index.html")
-          if (fs.existsSync(path.posix.join(argv.output, indexFp))) {
-            return redirect(fp + "/")
-          }
-        }
-
-        return serve()
-      })
-      server.listen(argv.port)
-      console.log(
-        chalk.cyan(
-          `Started a Quartz server listening at http://localhost:${argv.port}${argv.baseDir}`,
-        ),
-      )
-      console.log("hint: exit with ctrl+c")
-      chokidar
-        .watch(["**/*.ts", "**/*.tsx", "**/*.scss", "package.json"], {
-          ignoreInitial: true,
-        })
-        .on("all", async () => {
-          console.log(chalk.yellow("Detected a source code change, doing a hard rebuild..."))
-          rebuild(clientRefresh)
-        })
-    } else {
-      await build(() => {})
-      ctx.dispose()
-    }
   })
   .showHelpOnFail(false)
   .help()

quartz/build.ts

@@ -3,13 +3,13 @@ sourceMapSupport.install(options)
 import path from "path"
 import { PerfTimer } from "./util/perf"
 import { rimraf } from "rimraf"
-import { isGitIgnored } from "globby"
+import { GlobbyFilterFunction, isGitIgnored } from "globby"
 import chalk from "chalk"
 import { parseMarkdown } from "./processors/parse"
 import { filterContent } from "./processors/filter"
 import { emitContent } from "./processors/emit"
 import cfg from "../quartz.config"
-import { FilePath, joinSegments, slugifyFilePath } from "./util/path"
+import { FilePath, FullSlug, joinSegments, slugifyFilePath } from "./util/path"
 import chokidar from "chokidar"
 import { ProcessedContent } from "./plugins/vfile"
 import { Argv, BuildCtx } from "./util/ctx"
@@ -18,7 +18,20 @@ import { trace } from "./util/trace"
 import { options } from "./util/sourcemap"
 import { Mutex } from "async-mutex"
 
-async function buildQuartz(argv: Argv, clientRefresh: () => void) {
+type BuildData = {
+  ctx: BuildCtx
+  ignored: GlobbyFilterFunction
+  mut: Mutex
+  initialSlugs: FullSlug[]
+  // TODO merge contentMap and trackedAssets
+  contentMap: Map<FilePath, ProcessedContent>
+  trackedAssets: Set<FilePath>
+  toRebuild: Set<FilePath>
+  toRemove: Set<FilePath>
+  lastBuildMs: number
+}
+
+async function buildQuartz(argv: Argv, mut: Mutex, clientRefresh: () => void) {
   const ctx: BuildCtx = {
     argv,
     cfg,
@@ -38,13 +51,14 @@ async function buildQuartz(argv: Argv, clientRefresh: () => void) {
     console.log(`  Emitters: ${pluginNames("emitters").join(", ")}`)
   }
 
+  const release = await mut.acquire()
   perf.addEvent("clean")
   await rimraf(output)
   console.log(`Cleaned output directory \`${output}\` in ${perf.timeSince("clean")}`)
 
   perf.addEvent("glob")
   const allFiles = await glob("**/*.*", argv.directory, cfg.configuration.ignorePatterns)
-  const fps = allFiles.filter((fp) => fp.endsWith(".md"))
+  const fps = allFiles.filter((fp) => fp.endsWith(".md")).sort()
   console.log(
     `Found ${fps.length} input files from \`${argv.directory}\` in ${perf.timeSince("glob")}`,
   )
@@ -56,34 +70,76 @@ async function buildQuartz(argv: Argv, clientRefresh: () => void) {
   const filteredContent = filterContent(ctx, parsedFiles)
   await emitContent(ctx, filteredContent)
   console.log(chalk.green(`Done processing ${fps.length} files in ${perf.timeSince()}`))
+  release()
 
   if (argv.serve) {
-    return startServing(ctx, parsedFiles, clientRefresh)
+    return startServing(ctx, mut, parsedFiles, clientRefresh)
   }
 }
 
 // setup watcher for rebuilds
 async function startServing(
   ctx: BuildCtx,
+  mut: Mutex,
   initialContent: ProcessedContent[],
   clientRefresh: () => void,
 ) {
   const { argv } = ctx
 
-  const ignored = await isGitIgnored()
   const contentMap = new Map<FilePath, ProcessedContent>()
   for (const content of initialContent) {
     const [_tree, vfile] = content
     contentMap.set(vfile.data.filePath!, content)
   }
 
-  const initialSlugs = ctx.allSlugs
+  const buildData: BuildData = {
-  const buildMutex = new Mutex()
+    ctx,
-  const timeoutIds: Set<ReturnType<typeof setTimeout>> = new Set()
+    mut,
-  const toRebuild: Set<FilePath> = new Set()
+    contentMap,
-  const toRemove: Set<FilePath> = new Set()
+    ignored: await isGitIgnored(),
-  const trackedAssets: Set<FilePath> = new Set()
+    initialSlugs: ctx.allSlugs,
-  async function rebuild(fp: string, action: "add" | "change" | "delete") {
+    toRebuild: new Set<FilePath>(),
+    toRemove: new Set<FilePath>(),
+    trackedAssets: new Set<FilePath>(),
+    lastBuildMs: 0,
+  }
+
+  const watcher = chokidar.watch(".", {
+    persistent: true,
+    cwd: argv.directory,
+    ignoreInitial: true,
+  })
+
+  watcher
+    .on("add", (fp) => rebuildFromEntrypoint(fp, "add", clientRefresh, buildData))
+    .on("change", (fp) => rebuildFromEntrypoint(fp, "change", clientRefresh, buildData))
+    .on("unlink", (fp) => rebuildFromEntrypoint(fp, "delete", clientRefresh, buildData))
+
+  return async () => {
+    await watcher.close()
+  }
+}
+
+async function rebuildFromEntrypoint(
+  fp: string,
+  action: "add" | "change" | "delete",
+  clientRefresh: () => void,
+  buildData: BuildData, // note: this function mutates buildData
+) {
+  const {
+    ctx,
+    ignored,
+    mut,
+    initialSlugs,
+    contentMap,
+    toRebuild,
+    toRemove,
+    trackedAssets,
+    lastBuildMs,
+  } = buildData
+
+  const { argv } = ctx
+
   // don't do anything for gitignored files
   if (ignored(fp)) {
     return
@@ -108,12 +164,16 @@ async function startServing(
     toRemove.add(filePath)
   }
 
-    timeoutIds.forEach((id) => clearTimeout(id))
-
   // debounce rebuilds every 250ms
-    timeoutIds.add(
+
-      setTimeout(async () => {
+  const buildStart = new Date().getTime()
-        await buildMutex.acquire()
+  buildData.lastBuildMs = buildStart
+  const release = await mut.acquire()
+  if (lastBuildMs > buildStart) {
+    release()
+    return
+  }
+
   const perf = new PerfTimer()
   console.log(chalk.yellow("Detected change, rebuilding..."))
   try {
@@ -134,38 +194,30 @@ async function startServing(
       contentMap.delete(fp)
     }
 
-          await rimraf(argv.output)
     const parsedFiles = [...contentMap.values()]
     const filteredContent = filterContent(ctx, parsedFiles)
+
+    // TODO: we can probably traverse the link graph to figure out what's safe to delete here
+    // instead of just deleting everything
+    await rimraf(argv.output)
     await emitContent(ctx, filteredContent)
     console.log(chalk.green(`Done rebuilding in ${perf.timeSince()}`))
-        } catch {
+  } catch (err) {
     console.log(chalk.yellow(`Rebuild failed. Waiting on a change to fix the error...`))
+    if (argv.verbose) {
+      console.log(chalk.red(err))
+    }
   }
 
+  release()
   clientRefresh()
   toRebuild.clear()
   toRemove.clear()
-        buildMutex.release()
-      }, 250),
-    )
 }
 
-  const watcher = chokidar.watch(".", {
+export default async (argv: Argv, mut: Mutex, clientRefresh: () => void) => {
-    persistent: true,
-    cwd: argv.directory,
-    ignoreInitial: true,
-  })
-
-  watcher
-    .on("add", (fp) => rebuild(fp, "add"))
-    .on("change", (fp) => rebuild(fp, "change"))
-    .on("unlink", (fp) => rebuild(fp, "delete"))
-}
-
-export default async (argv: Argv, clientRefresh: () => void) => {
   try {
-    return await buildQuartz(argv, clientRefresh)
+    return await buildQuartz(argv, mut, clientRefresh)
   } catch (err) {
     trace("\nExiting Quartz due to a fatal error", err as Error)
   }

quartz/cfg.ts

@@ -1,3 +1,4 @@
+import { ValidDateType } from "./components/Date"
 import { QuartzComponent } from "./components/types"
 import { PluginTypes } from "./plugins/types"
 import { Theme } from "./util/theme"
@@ -6,11 +7,17 @@ export type Analytics =
   | null
   | {
       provider: "plausible"
+      host?: string
     }
   | {
       provider: "google"
       tagId: string
     }
+  | {
+      provider: "umami"
+      websiteId: string
+      host?: string
+    }
 
 export interface GlobalConfiguration {
   pageTitle: string
@@ -22,11 +29,19 @@ export interface GlobalConfiguration {
   analytics: Analytics
   /** Glob patterns to not search */
   ignorePatterns: string[]
+  /** Whether to use created, modified, or published as the default type of date */
+  defaultDateType: ValidDateType
   /** Base URL to use for CNAME files, sitemaps, and RSS feeds that require an absolute URL.
    *   Quartz will avoid using this as much as possible and use relative URLs most of the time
    */
   baseUrl?: string
   theme: Theme
+  /**
+   * The locale to use for date formatting. Default to "en-US"
+   * Allow to translate the date in the language of your choice.
+   * Need to be formated following the IETF language tag format (https://en.wikipedia.org/wiki/IETF_language_tag)
+   */
+  locale?: string
 }
 
 export interface QuartzConfig {

quartz/cli/args.js

@@ -0,0 +1,103 @@
+export const CommonArgv = {
+  directory: {
+    string: true,
+    alias: ["d"],
+    default: "content",
+    describe: "directory to look for content files",
+  },
+  verbose: {
+    boolean: true,
+    alias: ["v"],
+    default: false,
+    describe: "print out extra logging information",
+  },
+}
+
+export const CreateArgv = {
+  ...CommonArgv,
+  source: {
+    string: true,
+    alias: ["s"],
+    describe: "source directory to copy/create symlink from",
+  },
+  strategy: {
+    string: true,
+    alias: ["X"],
+    choices: ["new", "copy", "symlink"],
+    describe: "strategy for content folder setup",
+  },
+  links: {
+    string: true,
+    alias: ["l"],
+    choices: ["absolute", "shortest", "relative"],
+    describe: "strategy to resolve links",
+  },
+}
+
+export const SyncArgv = {
+  ...CommonArgv,
+  commit: {
+    boolean: true,
+    default: true,
+    describe: "create a git commit for your unsaved changes",
+  },
+  message: {
+    string: true,
+    alias: ["m"],
+    describe: "option to override the default Quartz commit message",
+  },
+  push: {
+    boolean: true,
+    default: true,
+    describe: "push updates to your Quartz fork",
+  },
+  pull: {
+    boolean: true,
+    default: true,
+    describe: "pull updates from your Quartz fork",
+  },
+}
+
+export const BuildArgv = {
+  ...CommonArgv,
+  output: {
+    string: true,
+    alias: ["o"],
+    default: "public",
+    describe: "output folder for files",
+  },
+  serve: {
+    boolean: true,
+    default: false,
+    describe: "run a local server to live-preview your Quartz",
+  },
+  baseDir: {
+    string: true,
+    default: "",
+    describe: "base path to serve your local server on",
+  },
+  port: {
+    number: true,
+    default: 8080,
+    describe: "port to serve Quartz on",
+  },
+  wsPort: {
+    number: true,
+    default: 3001,
+    describe: "port to use for WebSocket-based hot-reload notifications",
+  },
+  remoteDevHost: {
+    string: true,
+    default: "",
+    describe: "A URL override for the websocket connection if you are not developing on localhost",
+  },
+  bundleInfo: {
+    boolean: true,
+    default: false,
+    describe: "show detailed bundle information",
+  },
+  concurrency: {
+    number: true,
+    describe: "how many threads to use to parse notes",
+  },
+}

quartz/cli/constants.js

@@ -0,0 +1,15 @@
+import path from "path"
+import { readFileSync } from "fs"
+
+/**
+ * All constants relating to helpers or handlers
+ */
+export const ORIGIN_NAME = "origin"
+export const UPSTREAM_NAME = "upstream"
+export const QUARTZ_SOURCE_BRANCH = "v4"
+export const cwd = process.cwd()
+export const cacheDir = path.join(cwd, ".quartz-cache")
+export const cacheFile = "./quartz/.quartz-cache/transpiled-build.mjs"
+export const fp = "./quartz/build.ts"
+export const { version } = JSON.parse(readFileSync("./package.json").toString())
+export const contentCacheFolder = path.join(cacheDir, "content-cache")

quartz/cli/handlers.js

@@ -0,0 +1,544 @@
+import { promises } from "fs"
+import path from "path"
+import esbuild from "esbuild"
+import chalk from "chalk"
+import { sassPlugin } from "esbuild-sass-plugin"
+import fs from "fs"
+import { intro, outro, select, text } from "@clack/prompts"
+import { rimraf } from "rimraf"
+import chokidar from "chokidar"
+import prettyBytes from "pretty-bytes"
+import { execSync, spawnSync } from "child_process"
+import http from "http"
+import serveHandler from "serve-handler"
+import { WebSocketServer } from "ws"
+import { randomUUID } from "crypto"
+import { Mutex } from "async-mutex"
+import { CreateArgv } from "./args.js"
+import {
+  exitIfCancel,
+  escapePath,
+  gitPull,
+  popContentFolder,
+  stashContentFolder,
+} from "./helpers.js"
+import {
+  UPSTREAM_NAME,
+  QUARTZ_SOURCE_BRANCH,
+  ORIGIN_NAME,
+  version,
+  fp,
+  cacheFile,
+  cwd,
+} from "./constants.js"
+
+/**
+ * Handles `npx quartz create`
+ * @param {*} argv arguments for `create`
+ */
+export async function handleCreate(argv) {
+  console.log()
+  intro(chalk.bgGreen.black(` Quartz v${version} `))
+  const contentFolder = path.join(cwd, argv.directory)
+  let setupStrategy = argv.strategy?.toLowerCase()
+  let linkResolutionStrategy = argv.links?.toLowerCase()
+  const sourceDirectory = argv.source
+
+  // If all cmd arguments were provided, check if theyre valid
+  if (setupStrategy && linkResolutionStrategy) {
+    // If setup isn't, "new", source argument is required
+    if (setupStrategy !== "new") {
+      // Error handling
+      if (!sourceDirectory) {
+        outro(
+          chalk.red(
+            `Setup strategies (arg '${chalk.yellow(
+              `-${CreateArgv.strategy.alias[0]}`,
+            )}') other than '${chalk.yellow(
+              "new",
+            )}' require content folder argument ('${chalk.yellow(
+              `-${CreateArgv.source.alias[0]}`,
+            )}') to be set`,
+          ),
+        )
+        process.exit(1)
+      } else {
+        if (!fs.existsSync(sourceDirectory)) {
+          outro(
+            chalk.red(
+              `Input directory to copy/symlink 'content' from not found ('${chalk.yellow(
+                sourceDirectory,
+              )}', invalid argument "${chalk.yellow(`-${CreateArgv.source.alias[0]}`)})`,
+            ),
+          )
+          process.exit(1)
+        } else if (!fs.lstatSync(sourceDirectory).isDirectory()) {
+          outro(
+            chalk.red(
+              `Source directory to copy/symlink 'content' from is not a directory (found file at '${chalk.yellow(
+                sourceDirectory,
+              )}', invalid argument ${chalk.yellow(`-${CreateArgv.source.alias[0]}`)}")`,
+            ),
+          )
+          process.exit(1)
+        }
+      }
+    }
+  }
+
+  // Use cli process if cmd args werent provided
+  if (!setupStrategy) {
+    setupStrategy = exitIfCancel(
+      await select({
+        message: `Choose how to initialize the content in \`${contentFolder}\``,
+        options: [
+          { value: "new", label: "Empty Quartz" },
+          { value: "copy", label: "Copy an existing folder", hint: "overwrites `content`" },
+          {
+            value: "symlink",
+            label: "Symlink an existing folder",
+            hint: "don't select this unless you know what you are doing!",
+          },
+        ],
+      }),
+    )
+  }
+
+  async function rmContentFolder() {
+    const contentStat = await fs.promises.lstat(contentFolder)
+    if (contentStat.isSymbolicLink()) {
+      await fs.promises.unlink(contentFolder)
+    } else {
+      await rimraf(contentFolder)
+    }
+  }
+
+  const gitkeepPath = path.join(contentFolder, ".gitkeep")
+  if (fs.existsSync(gitkeepPath)) {
+    await fs.promises.unlink(gitkeepPath)
+  }
+  if (setupStrategy === "copy" || setupStrategy === "symlink") {
+    let originalFolder = sourceDirectory
+
+    // If input directory was not passed, use cli
+    if (!sourceDirectory) {
+      originalFolder = escapePath(
+        exitIfCancel(
+          await text({
+            message: "Enter the full path to existing content folder",
+            placeholder:
+              "On most terminal emulators, you can drag and drop a folder into the window and it will paste the full path",
+            validate(fp) {
+              const fullPath = escapePath(fp)
+              if (!fs.existsSync(fullPath)) {
+                return "The given path doesn't exist"
+              } else if (!fs.lstatSync(fullPath).isDirectory()) {
+                return "The given path is not a folder"
+              }
+            },
+          }),
+        ),
+      )
+    }
+
+    await rmContentFolder()
+    if (setupStrategy === "copy") {
+      await fs.promises.cp(originalFolder, contentFolder, {
+        recursive: true,
+        preserveTimestamps: true,
+      })
+    } else if (setupStrategy === "symlink") {
+      await fs.promises.symlink(originalFolder, contentFolder, "dir")
+    }
+  } else if (setupStrategy === "new") {
+    await fs.promises.writeFile(
+      path.join(contentFolder, "index.md"),
+      `---
+title: Welcome to Quartz
+---
+
+This is a blank Quartz installation.
+See the [documentation](https://quartz.jzhao.xyz) for how to get started.
+`,
+    )
+  }
+
+  // Use cli process if cmd args werent provided
+  if (!linkResolutionStrategy) {
+    // get a preferred link resolution strategy
+    linkResolutionStrategy = exitIfCancel(
+      await select({
+        message: `Choose how Quartz should resolve links in your content. This should match Obsidian's link format. You can change this later in \`quartz.config.ts\`.`,
+        options: [
+          {
+            value: "shortest",
+            label: "Treat links as shortest path",
+            hint: "(default)",
+          },
+          {
+            value: "absolute",
+            label: "Treat links as absolute path",
+          },
+          {
+            value: "relative",
+            label: "Treat links as relative paths",
+          },
+        ],
+      }),
+    )
+  }
+
+  // now, do config changes
+  const configFilePath = path.join(cwd, "quartz.config.ts")
+  let configContent = await fs.promises.readFile(configFilePath, { encoding: "utf-8" })
+  configContent = configContent.replace(
+    /markdownLinkResolution: '(.+)'/,
+    `markdownLinkResolution: '${linkResolutionStrategy}'`,
+  )
+  await fs.promises.writeFile(configFilePath, configContent)
+
+  // setup remote
+  execSync(
+    `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`,
+    { stdio: "ignore" },
+  )
+
+  outro(`You're all set! Not sure what to do next? Try:
+  • Customizing Quartz a bit more by editing \`quartz.config.ts\`
+  • Running \`npx quartz build --serve\` to preview your Quartz locally
+  • Hosting your Quartz online (see: https://quartz.jzhao.xyz/hosting)
+`)
+}
+
+/**
+ * Handles `npx quartz build`
+ * @param {*} argv arguments for `build`
+ */
+export async function handleBuild(argv) {
+  console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
+  const ctx = await esbuild.context({
+    entryPoints: [fp],
+    outfile: cacheFile,
+    bundle: true,
+    keepNames: true,
+    minifyWhitespace: true,
+    minifySyntax: true,
+    platform: "node",
+    format: "esm",
+    jsx: "automatic",
+    jsxImportSource: "preact",
+    packages: "external",
+    metafile: true,
+    sourcemap: true,
+    sourcesContent: false,
+    plugins: [
+      sassPlugin({
+        type: "css-text",
+        cssImports: true,
+      }),
+      {
+        name: "inline-script-loader",
+        setup(build) {
+          build.onLoad({ filter: /\.inline\.(ts|js)$/ }, async (args) => {
+            let text = await promises.readFile(args.path, "utf8")
+
+            // remove default exports that we manually inserted
+            text = text.replace("export default", "")
+            text = text.replace("export", "")
+
+            const sourcefile = path.relative(path.resolve("."), args.path)
+            const resolveDir = path.dirname(sourcefile)
+            const transpiled = await esbuild.build({
+              stdin: {
+                contents: text,
+                loader: "ts",
+                resolveDir,
+                sourcefile,
+              },
+              write: false,
+              bundle: true,
+              minify: true,
+              platform: "browser",
+              format: "esm",
+            })
+            const rawMod = transpiled.outputFiles[0].text
+            return {
+              contents: rawMod,
+              loader: "text",
+            }
+          })
+        },
+      },
+    ],
+  })
+
+  const buildMutex = new Mutex()
+  let lastBuildMs = 0
+  let cleanupBuild = null
+  const build = async (clientRefresh) => {
+    const buildStart = new Date().getTime()
+    lastBuildMs = buildStart
+    const release = await buildMutex.acquire()
+    if (lastBuildMs > buildStart) {
+      release()
+      return
+    }
+
+    if (cleanupBuild) {
+      await cleanupBuild()
+      console.log(chalk.yellow("Detected a source code change, doing a hard rebuild..."))
+    }
+
+    const result = await ctx.rebuild().catch((err) => {
+      console.error(`${chalk.red("Couldn't parse Quartz configuration:")} ${fp}`)
+      console.log(`Reason: ${chalk.grey(err)}`)
+      process.exit(1)
+    })
+    release()
+
+    if (argv.bundleInfo) {
+      const outputFileName = "quartz/.quartz-cache/transpiled-build.mjs"
+      const meta = result.metafile.outputs[outputFileName]
+      console.log(
+        `Successfully transpiled ${Object.keys(meta.inputs).length} files (${prettyBytes(
+          meta.bytes,
+        )})`,
+      )
+      console.log(await esbuild.analyzeMetafile(result.metafile, { color: true }))
+    }
+
+    // bypass module cache
+    // https://github.com/nodejs/modules/issues/307
+    const { default: buildQuartz } = await import(`../../${cacheFile}?update=${randomUUID()}`)
+    // ^ this import is relative, so base "cacheFile" path can't be used
+
+    cleanupBuild = await buildQuartz(argv, buildMutex, clientRefresh)
+    clientRefresh()
+  }
+
+  if (argv.serve) {
+    const connections = []
+    const clientRefresh = () => connections.forEach((conn) => conn.send("rebuild"))
+
+    if (argv.baseDir !== "" && !argv.baseDir.startsWith("/")) {
+      argv.baseDir = "/" + argv.baseDir
+    }
+
+    await build(clientRefresh)
+    const server = http.createServer(async (req, res) => {
+      if (argv.baseDir && !req.url?.startsWith(argv.baseDir)) {
+        console.log(
+          chalk.red(
+            `[404] ${req.url} (warning: link outside of site, this is likely a Quartz bug)`,
+          ),
+        )
+        res.writeHead(404)
+        res.end()
+        return
+      }
+
+      // strip baseDir prefix
+      req.url = req.url?.slice(argv.baseDir.length)
+
+      const serve = async () => {
+        const release = await buildMutex.acquire()
+        await serveHandler(req, res, {
+          public: argv.output,
+          directoryListing: false,
+          headers: [
+            {
+              source: "**/*.*",
+              headers: [{ key: "Content-Disposition", value: "inline" }],
+            },
+          ],
+        })
+        const status = res.statusCode
+        const statusString =
+          status >= 200 && status < 300 ? chalk.green(`[${status}]`) : chalk.red(`[${status}]`)
+        console.log(statusString + chalk.grey(` ${argv.baseDir}${req.url}`))
+        release()
+      }
+
+      const redirect = (newFp) => {
+        newFp = argv.baseDir + newFp
+        res.writeHead(302, {
+          Location: newFp,
+        })
+        console.log(chalk.yellow("[302]") + chalk.grey(` ${argv.baseDir}${req.url} -> ${newFp}`))
+        res.end()
+      }
+
+      let fp = req.url?.split("?")[0] ?? "/"
+
+      // handle redirects
+      if (fp.endsWith("/")) {
+        // /trailing/
+        // does /trailing/index.html exist? if so, serve it
+        const indexFp = path.posix.join(fp, "index.html")
+        if (fs.existsSync(path.posix.join(argv.output, indexFp))) {
+          req.url = fp
+          return serve()
+        }
+
+        // does /trailing.html exist? if so, redirect to /trailing
+        let base = fp.slice(0, -1)
+        if (path.extname(base) === "") {
+          base += ".html"
+        }
+        if (fs.existsSync(path.posix.join(argv.output, base))) {
+          return redirect(fp.slice(0, -1))
+        }
+      } else {
+        // /regular
+        // does /regular.html exist? if so, serve it
+        let base = fp
+        if (path.extname(base) === "") {
+          base += ".html"
+        }
+        if (fs.existsSync(path.posix.join(argv.output, base))) {
+          req.url = fp
+          return serve()
+        }
+
+        // does /regular/index.html exist? if so, redirect to /regular/
+        let indexFp = path.posix.join(fp, "index.html")
+        if (fs.existsSync(path.posix.join(argv.output, indexFp))) {
+          return redirect(fp + "/")
+        }
+      }
+
+      return serve()
+    })
+    server.listen(argv.port)
+    const wss = new WebSocketServer({ port: argv.wsPort })
+    wss.on("connection", (ws) => connections.push(ws))
+    console.log(
+      chalk.cyan(
+        `Started a Quartz server listening at http://localhost:${argv.port}${argv.baseDir}`,
+      ),
+    )
+    console.log("hint: exit with ctrl+c")
+    chokidar
+      .watch(["**/*.ts", "**/*.tsx", "**/*.scss", "package.json"], {
+        ignoreInitial: true,
+      })
+      .on("all", async () => {
+        build(clientRefresh)
+      })
+  } else {
+    await build(() => {})
+    ctx.dispose()
+  }
+}
+
+/**
+ * Handles `npx quartz update`
+ * @param {*} argv arguments for `update`
+ */
+export async function handleUpdate(argv) {
+  const contentFolder = path.join(cwd, argv.directory)
+  console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
+  console.log("Backing up your content")
+  execSync(
+    `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`,
+  )
+  await stashContentFolder(contentFolder)
+  console.log(
+    "Pulling updates... you may need to resolve some `git` conflicts if you've made changes to components or plugins.",
+  )
+
+  try {
+    gitPull(UPSTREAM_NAME, QUARTZ_SOURCE_BRANCH)
+  } catch {
+    console.log(chalk.red("An error occurred above while pulling updates."))
+    await popContentFolder(contentFolder)
+    return
+  }
+
+  await popContentFolder(contentFolder)
+  console.log("Ensuring dependencies are up to date")
+  const res = spawnSync("npm", ["i"], { stdio: "inherit" })
+  if (res.status === 0) {
+    console.log(chalk.green("Done!"))
+  } else {
+    console.log(chalk.red("An error occurred above while installing dependencies."))
+  }
+}
+
+/**
+ * Handles `npx quartz restore`
+ * @param {*} argv arguments for `restore`
+ */
+export async function handleRestore(argv) {
+  const contentFolder = path.join(cwd, argv.directory)
+  await popContentFolder(contentFolder)
+}
+
+/**
+ * Handles `npx quartz sync`
+ * @param {*} argv arguments for `sync`
+ */
+export async function handleSync(argv) {
+  const contentFolder = path.join(cwd, argv.directory)
+  console.log(chalk.bgGreen.black(`\n Quartz v${version} \n`))
+  console.log("Backing up your content")
+
+  if (argv.commit) {
+    const contentStat = await fs.promises.lstat(contentFolder)
+    if (contentStat.isSymbolicLink()) {
+      const linkTarg = await fs.promises.readlink(contentFolder)
+      console.log(chalk.yellow("Detected symlink, trying to dereference before committing"))
+
+      // stash symlink file
+      await stashContentFolder(contentFolder)
+
+      // follow symlink and copy content
+      await fs.promises.cp(linkTarg, contentFolder, {
+        recursive: true,
+        preserveTimestamps: true,
+      })
+    }
+
+    const currentTimestamp = new Date().toLocaleString("en-US", {
+      dateStyle: "medium",
+      timeStyle: "short",
+    })
+    const commitMessage = argv.message ?? `Quartz sync: ${currentTimestamp}`
+    spawnSync("git", ["add", "."], { stdio: "inherit" })
+    spawnSync("git", ["commit", "-m", commitMessage], { stdio: "inherit" })
+
+    if (contentStat.isSymbolicLink()) {
+      // put symlink back
+      await popContentFolder(contentFolder)
+    }
+  }
+
+  await stashContentFolder(contentFolder)
+
+  if (argv.pull) {
+    console.log(
+      "Pulling updates from your repository. You may need to resolve some `git` conflicts if you've made changes to components or plugins.",
+    )
+    try {
+      gitPull(ORIGIN_NAME, QUARTZ_SOURCE_BRANCH)
+    } catch {
+      console.log(chalk.red("An error occurred above while pulling updates."))
+      await popContentFolder(contentFolder)
+      return
+    }
+  }
+
+  await popContentFolder(contentFolder)
+  if (argv.push) {
+    console.log("Pushing your changes")
+    const res = spawnSync("git", ["push", "-uf", ORIGIN_NAME, QUARTZ_SOURCE_BRANCH], {
+      stdio: "inherit",
+    })
+    if (res.status !== 0) {
+      console.log(chalk.red(`An error occurred above while pushing to remote ${ORIGIN_NAME}.`))
+      return
+    }
+  }
+
+  console.log(chalk.green("Done!"))
+}

quartz/cli/helpers.js

@@ -0,0 +1,54 @@
+import { isCancel, outro } from "@clack/prompts"
+import chalk from "chalk"
+import { contentCacheFolder } from "./constants.js"
+import { spawnSync } from "child_process"
+import fs from "fs"
+
+export function escapePath(fp) {
+  return fp
+    .replace(/\\ /g, " ") // unescape spaces
+    .replace(/^".*"$/, "$1")
+    .replace(/^'.*"$/, "$1")
+    .trim()
+}
+
+export function exitIfCancel(val) {
+  if (isCancel(val)) {
+    outro(chalk.red("Exiting"))
+    process.exit(0)
+  } else {
+    return val
+  }
+}
+
+export async function stashContentFolder(contentFolder) {
+  await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
+  await fs.promises.cp(contentFolder, contentCacheFolder, {
+    force: true,
+    recursive: true,
+    verbatimSymlinks: true,
+    preserveTimestamps: true,
+  })
+  await fs.promises.rm(contentFolder, { force: true, recursive: true })
+}
+
+export function gitPull(origin, branch) {
+  const flags = ["--no-rebase", "--autostash", "-s", "recursive", "-X", "ours", "--no-edit"]
+  const out = spawnSync("git", ["pull", ...flags, origin, branch], { stdio: "inherit" })
+  if (out.stderr) {
+    throw new Error(chalk.red(`Error while pulling updates: ${out.stderr}`))
+  } else if (out.status !== 0) {
+    throw new Error(chalk.red("Error while pulling updates"))
+  }
+}
+
+export async function popContentFolder(contentFolder) {
+  await fs.promises.rm(contentFolder, { force: true, recursive: true })
+  await fs.promises.cp(contentCacheFolder, contentFolder, {
+    force: true,
+    recursive: true,
+    verbatimSymlinks: true,
+    preserveTimestamps: true,
+  })
+  await fs.promises.rm(contentCacheFolder, { force: true, recursive: true })
+}

quartz/components/ArticleTitle.tsx

@@ -1,9 +1,10 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
 
-function ArticleTitle({ fileData }: QuartzComponentProps) {
+function ArticleTitle({ fileData, displayClass }: QuartzComponentProps) {
   const title = fileData.frontmatter?.title
   if (title) {
-    return <h1 class="article-title">{title}</h1>
+    return <h1 class={classNames(displayClass, "article-title")}>{title}</h1>
   } else {
     return null
   }

quartz/components/Backlinks.tsx

@@ -1,12 +1,13 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import style from "./styles/backlinks.scss"
 import { resolveRelative, simplifySlug } from "../util/path"
+import { classNames } from "../util/lang"
 
-function Backlinks({ fileData, allFiles }: QuartzComponentProps) {
+function Backlinks({ fileData, allFiles, displayClass }: QuartzComponentProps) {
   const slug = simplifySlug(fileData.slug!)
   const backlinkFiles = allFiles.filter((file) => file.links?.includes(slug))
   return (
-    <div class="backlinks">
+    <div class={classNames(displayClass, "backlinks")}>
       <h3>Backlinks</h3>
       <ul class="overflow">
         {backlinkFiles.length > 0 ? (

quartz/components/Breadcrumbs.tsx

@@ -0,0 +1,129 @@
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import breadcrumbsStyle from "./styles/breadcrumbs.scss"
+import { FullSlug, SimpleSlug, resolveRelative } from "../util/path"
+import { QuartzPluginData } from "../plugins/vfile"
+import { classNames } from "../util/lang"
+
+type CrumbData = {
+  displayName: string
+  path: string
+}
+
+interface BreadcrumbOptions {
+  /**
+   * Symbol between crumbs
+   */
+  spacerSymbol: string
+  /**
+   * Name of first crumb
+   */
+  rootName: string
+  /**
+   * Whether to look up frontmatter title for folders (could cause performance problems with big vaults)
+   */
+  resolveFrontmatterTitle: boolean
+  /**
+   * Whether to display breadcrumbs on root `index.md`
+   */
+  hideOnRoot: boolean
+  /**
+   * Whether to display the current page in the breadcrumbs.
+   */
+  showCurrentPage: boolean
+}
+
+const defaultOptions: BreadcrumbOptions = {
+  spacerSymbol: "❯",
+  rootName: "Home",
+  resolveFrontmatterTitle: true,
+  hideOnRoot: true,
+  showCurrentPage: true,
+}
+
+function formatCrumb(displayName: string, baseSlug: FullSlug, currentSlug: SimpleSlug): CrumbData {
+  return {
+    displayName: displayName.replaceAll("-", " "),
+    path: resolveRelative(baseSlug, currentSlug),
+  }
+}
+
+export default ((opts?: Partial<BreadcrumbOptions>) => {
+  // Merge options with defaults
+  const options: BreadcrumbOptions = { ...defaultOptions, ...opts }
+
+  // computed index of folder name to its associated file data
+  let folderIndex: Map<string, QuartzPluginData> | undefined
+
+  function Breadcrumbs({ fileData, allFiles, displayClass }: QuartzComponentProps) {
+    // Hide crumbs on root if enabled
+    if (options.hideOnRoot && fileData.slug === "index") {
+      return <></>
+    }
+
+    // Format entry for root element
+    const firstEntry = formatCrumb(options.rootName, fileData.slug!, "/" as SimpleSlug)
+    const crumbs: CrumbData[] = [firstEntry]
+
+    if (!folderIndex && options.resolveFrontmatterTitle) {
+      folderIndex = new Map()
+      // construct the index for the first time
+      for (const file of allFiles) {
+        if (file.slug?.endsWith("index")) {
+          const folderParts = file.slug?.split("/")
+          // 2nd last to exclude the /index
+          const folderName = folderParts?.at(-2)
+          if (folderName) {
+            folderIndex.set(folderName, file)
+          }
+        }
+      }
+    }
+
+    // Split slug into hierarchy/parts
+    const slugParts = fileData.slug?.split("/")
+    if (slugParts) {
+      // full path until current part
+      let currentPath = ""
+      for (let i = 0; i < slugParts.length - 1; i++) {
+        let curPathSegment = slugParts[i]
+
+        // Try to resolve frontmatter folder title
+        const currentFile = folderIndex?.get(curPathSegment)
+        if (currentFile) {
+          const title = currentFile.frontmatter!.title
+          if (title !== "index") {
+            curPathSegment = title
+          }
+        }
+
+        // Add current slug to full path
+        currentPath += slugParts[i] + "/"
+
+        // Format and add current crumb
+        const crumb = formatCrumb(curPathSegment, fileData.slug!, currentPath as SimpleSlug)
+        crumbs.push(crumb)
+      }
+
+      // Add current file to crumb (can directly use frontmatter title)
+      if (options.showCurrentPage && slugParts.at(-1) !== "index") {
+        crumbs.push({
+          displayName: fileData.frontmatter!.title,
+          path: "",
+        })
+      }
+    }
+
+    return (
+      <nav class={classNames(displayClass, "breadcrumb-container")} aria-label="breadcrumbs">
+        {crumbs.map((crumb, index) => (
+          <div class="breadcrumb-element">
+            <a href={crumb.path}>{crumb.displayName}</a>
+            {index !== crumbs.length - 1 && <p>{` ${options.spacerSymbol} `}</p>}
+          </div>
+        ))}
+      </nav>
+    )
+  }
+  Breadcrumbs.css = breadcrumbsStyle
+  return Breadcrumbs
+}) satisfies QuartzComponentConstructor

quartz/components/ContentMeta.tsx

@@ -1,19 +1,40 @@
-import { formatDate } from "./Date"
+import { formatDate, getDate } from "./Date"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import readingTime from "reading-time"
+import { classNames } from "../util/lang"
 
-export default (() => {
+interface ContentMetaOptions {
-  function ContentMetadata({ fileData }: QuartzComponentProps) {
+  /**
-    const text = fileData.text
+   * Whether to display reading time
-    if (text) {
+   */
-      const segments: string[] = []
+  showReadingTime: boolean
-      const { text: timeTaken, words: _words } = readingTime(text)
-      if (fileData.dates?.modified) {
-        segments.push(formatDate(fileData.dates.modified))
 }
 
+const defaultOptions: ContentMetaOptions = {
+  showReadingTime: true,
+}
+
+export default ((opts?: Partial<ContentMetaOptions>) => {
+  // Merge options with defaults
+  const options: ContentMetaOptions = { ...defaultOptions, ...opts }
+
+  function ContentMetadata({ cfg, fileData, displayClass }: QuartzComponentProps) {
+    const text = fileData.text
+
+    if (text) {
+      const segments: string[] = []
+
+      if (fileData.dates) {
+        segments.push(formatDate(getDate(cfg, fileData)!, cfg.locale))
+      }
+
+      // Display reading time if enabled
+      if (options.showReadingTime) {
+        const { text: timeTaken, words: _words } = readingTime(text)
         segments.push(timeTaken)
-      return <p class="content-meta">{segments.join(", ")}</p>
+      }
+
+      return <p class={classNames(displayClass, "content-meta")}>{segments.join(", ")}</p>
     } else {
       return null
     }

quartz/components/Darkmode.tsx

@@ -3,11 +3,12 @@
 // see: https://v8.dev/features/modules#defer
 import darkmodeScript from "./scripts/darkmode.inline"
 import styles from "./styles/darkmode.scss"
-import { QuartzComponentConstructor } from "./types"
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
 
-function Darkmode() {
+function Darkmode({ displayClass }: QuartzComponentProps) {
   return (
-    <div class="darkmode">
+    <div class={classNames(displayClass, "darkmode")}>
       <input class="toggle" id="darkmode-toggle" type="checkbox" tabIndex={-1} />
       <label id="toggle-label-light" for="darkmode-toggle" tabIndex={-1}>
         <svg
@@ -18,7 +19,7 @@ function Darkmode() {
           x="0px"
           y="0px"
           viewBox="0 0 35 35"
-          style="enable-background:new 0 0 35 35;"
+          style="enable-background:new 0 0 35 35"
           xmlSpace="preserve"
         >
           <title>Light mode</title>
@@ -34,7 +35,7 @@ function Darkmode() {
           x="0px"
           y="0px"
           viewBox="0 0 100 100"
-          style="enable-background='new 0 0 100 100'"
+          style="enable-background:new 0 0 100 100"
           xmlSpace="preserve"
         >
           <title>Dark mode</title>

quartz/components/Date.tsx

@@ -1,15 +1,30 @@
+import { GlobalConfiguration } from "../cfg"
+import { QuartzPluginData } from "../plugins/vfile"
+
 interface Props {
   date: Date
+  locale?: string
 }
 
-export function formatDate(d: Date): string {
+export type ValidDateType = keyof Required<QuartzPluginData>["dates"]
-  return d.toLocaleDateString("en-US", {
+
+export function getDate(cfg: GlobalConfiguration, data: QuartzPluginData): Date | undefined {
+  if (!cfg.defaultDateType) {
+    throw new Error(
+      `Field 'defaultDateType' was not set in the configuration object of quartz.config.ts. See https://quartz.jzhao.xyz/configuration#general-configuration for more details.`,
+    )
+  }
+  return data.dates?.[cfg.defaultDateType]
+}
+
+export function formatDate(d: Date, locale = "en-US"): string {
+  return d.toLocaleDateString(locale, {
     year: "numeric",
     month: "short",
     day: "2-digit",
   })
 }
 
-export function Date({ date }: Props) {
+export function Date({ date, locale }: Props) {
-  return <>{formatDate(date)}</>
+  return <>{formatDate(date, locale)}</>
 }

quartz/components/Explorer.tsx

@@ -0,0 +1,119 @@
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import explorerStyle from "./styles/explorer.scss"
+
+// @ts-ignore
+import script from "./scripts/explorer.inline"
+import { ExplorerNode, FileNode, Options } from "./ExplorerNode"
+import { QuartzPluginData } from "../plugins/vfile"
+import { classNames } from "../util/lang"
+
+// Options interface defined in `ExplorerNode` to avoid circular dependency
+const defaultOptions = {
+  title: "Explorer",
+  folderClickBehavior: "collapse",
+  folderDefaultState: "collapsed",
+  useSavedState: true,
+  mapFn: (node) => {
+    return node
+  },
+  sortFn: (a, b) => {
+    // Sort order: folders first, then files. Sort folders and files alphabetically
+    if ((!a.file && !b.file) || (a.file && b.file)) {
+      // numeric: true: Whether numeric collation should be used, such that "1" < "2" < "10"
+      // sensitivity: "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A
+      return a.displayName.localeCompare(b.displayName, undefined, {
+        numeric: true,
+        sensitivity: "base",
+      })
+    }
+
+    if (a.file && !b.file) {
+      return 1
+    } else {
+      return -1
+    }
+  },
+  filterFn: (node) => node.name !== "tags",
+  order: ["filter", "map", "sort"],
+} satisfies Options
+
+export default ((userOpts?: Partial<Options>) => {
+  // Parse config
+  const opts: Options = { ...defaultOptions, ...userOpts }
+
+  // memoized
+  let fileTree: FileNode
+  let jsonTree: string
+
+  function constructFileTree(allFiles: QuartzPluginData[]) {
+    if (fileTree) {
+      return
+    }
+
+    // Construct tree from allFiles
+    fileTree = new FileNode("")
+    allFiles.forEach((file) => fileTree.add(file))
+
+    // Execute all functions (sort, filter, map) that were provided (if none were provided, only default "sort" is applied)
+    if (opts.order) {
+      // Order is important, use loop with index instead of order.map()
+      for (let i = 0; i < opts.order.length; i++) {
+        const functionName = opts.order[i]
+        if (functionName === "map") {
+          fileTree.map(opts.mapFn)
+        } else if (functionName === "sort") {
+          fileTree.sort(opts.sortFn)
+        } else if (functionName === "filter") {
+          fileTree.filter(opts.filterFn)
+        }
+      }
+    }
+
+    // Get all folders of tree. Initialize with collapsed state
+    // Stringify to pass json tree as data attribute ([data-tree])
+    const folders = fileTree.getFolderPaths(opts.folderDefaultState === "collapsed")
+    jsonTree = JSON.stringify(folders)
+  }
+
+  function Explorer({ allFiles, displayClass, fileData }: QuartzComponentProps) {
+    constructFileTree(allFiles)
+    return (
+      <div class={classNames(displayClass, "explorer")}>
+        <button
+          type="button"
+          id="explorer"
+          data-behavior={opts.folderClickBehavior}
+          data-collapsed={opts.folderDefaultState}
+          data-savestate={opts.useSavedState}
+          data-tree={jsonTree}
+        >
+          <h1>{opts.title}</h1>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="14"
+            height="14"
+            viewBox="5 8 14 8"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            class="fold"
+          >
+            <polyline points="6 9 12 15 18 9"></polyline>
+          </svg>
+        </button>
+        <div id="explorer-content">
+          <ul class="overflow" id="explorer-ul">
+            <ExplorerNode node={fileTree} opts={opts} fileData={fileData} />
+            <li id="explorer-end" />
+          </ul>
+        </div>
+      </div>
+    )
+  }
+
+  Explorer.css = explorerStyle
+  Explorer.afterDOMLoaded = script
+  return Explorer
+}) satisfies QuartzComponentConstructor

quartz/components/ExplorerNode.tsx

@@ -0,0 +1,248 @@
+// @ts-ignore
+import { QuartzPluginData } from "../plugins/vfile"
+import {
+  joinSegments,
+  resolveRelative,
+  clone,
+  simplifySlug,
+  SimpleSlug,
+  FilePath,
+} from "../util/path"
+
+type OrderEntries = "sort" | "filter" | "map"
+
+export interface Options {
+  title: string
+  folderDefaultState: "collapsed" | "open"
+  folderClickBehavior: "collapse" | "link"
+  useSavedState: boolean
+  sortFn: (a: FileNode, b: FileNode) => number
+  filterFn: (node: FileNode) => boolean
+  mapFn: (node: FileNode) => void
+  order: OrderEntries[]
+}
+
+type DataWrapper = {
+  file: QuartzPluginData
+  path: string[]
+}
+
+export type FolderState = {
+  path: string
+  collapsed: boolean
+}
+
+function getPathSegment(fp: FilePath | undefined, idx: number): string | undefined {
+  if (!fp) {
+    return undefined
+  }
+
+  return fp.split("/").at(idx)
+}
+
+// Structure to add all files into a tree
+export class FileNode {
+  children: Array<FileNode>
+  name: string // this is the slug segment
+  displayName: string
+  file: QuartzPluginData | null
+  depth: number
+
+  constructor(slugSegment: string, displayName?: string, file?: QuartzPluginData, depth?: number) {
+    this.children = []
+    this.name = slugSegment
+    this.displayName = displayName ?? file?.frontmatter?.title ?? slugSegment
+    this.file = file ? clone(file) : null
+    this.depth = depth ?? 0
+  }
+
+  private insert(fileData: DataWrapper) {
+    if (fileData.path.length === 0) {
+      return
+    }
+
+    const nextSegment = fileData.path[0]
+
+    // base case, insert here
+    if (fileData.path.length === 1) {
+      if (nextSegment === "") {
+        // index case (we are the root and we just found index.md), set our data appropriately
+        const title = fileData.file.frontmatter?.title
+        if (title && title !== "index") {
+          this.displayName = title
+        }
+      } else {
+        // direct child
+        this.children.push(new FileNode(nextSegment, undefined, fileData.file, this.depth + 1))
+      }
+
+      return
+    }
+
+    // find the right child to insert into
+    fileData.path = fileData.path.splice(1)
+    const child = this.children.find((c) => c.name === nextSegment)
+    if (child) {
+      child.insert(fileData)
+      return
+    }
+
+    const newChild = new FileNode(
+      nextSegment,
+      getPathSegment(fileData.file.relativePath, this.depth),
+      undefined,
+      this.depth + 1,
+    )
+    newChild.insert(fileData)
+    this.children.push(newChild)
+  }
+
+  // Add new file to tree
+  add(file: QuartzPluginData) {
+    this.insert({ file: file, path: simplifySlug(file.slug!).split("/") })
+  }
+
+  /**
+   * Filter FileNode tree. Behaves similar to `Array.prototype.filter()`, but modifies tree in place
+   * @param filterFn function to filter tree with
+   */
+  filter(filterFn: (node: FileNode) => boolean) {
+    this.children = this.children.filter(filterFn)
+    this.children.forEach((child) => child.filter(filterFn))
+  }
+
+  /**
+   * Filter FileNode tree. Behaves similar to `Array.prototype.map()`, but modifies tree in place
+   * @param mapFn function to use for mapping over tree
+   */
+  map(mapFn: (node: FileNode) => void) {
+    mapFn(this)
+    this.children.forEach((child) => child.map(mapFn))
+  }
+
+  /**
+   * Get folder representation with state of tree.
+   * Intended to only be called on root node before changes to the tree are made
+   * @param collapsed default state of folders (collapsed by default or not)
+   * @returns array containing folder state for tree
+   */
+  getFolderPaths(collapsed: boolean): FolderState[] {
+    const folderPaths: FolderState[] = []
+
+    const traverse = (node: FileNode, currentPath: string) => {
+      if (!node.file) {
+        const folderPath = joinSegments(currentPath, node.name)
+        if (folderPath !== "") {
+          folderPaths.push({ path: folderPath, collapsed })
+        }
+
+        node.children.forEach((child) => traverse(child, folderPath))
+      }
+    }
+
+    traverse(this, "")
+    return folderPaths
+  }
+
+  // Sort order: folders first, then files. Sort folders and files alphabetically
+  /**
+   * Sorts tree according to sort/compare function
+   * @param sortFn compare function used for `.sort()`, also used recursively for children
+   */
+  sort(sortFn: (a: FileNode, b: FileNode) => number) {
+    this.children = this.children.sort(sortFn)
+    this.children.forEach((e) => e.sort(sortFn))
+  }
+}
+
+type ExplorerNodeProps = {
+  node: FileNode
+  opts: Options
+  fileData: QuartzPluginData
+  fullPath?: string
+}
+
+export function ExplorerNode({ node, opts, fullPath, fileData }: ExplorerNodeProps) {
+  // Get options
+  const folderBehavior = opts.folderClickBehavior
+  const isDefaultOpen = opts.folderDefaultState === "open"
+
+  // Calculate current folderPath
+  let folderPath = ""
+  if (node.name !== "") {
+    folderPath = joinSegments(fullPath ?? "", node.name)
+  }
+
+  return (
+    <>
+      {node.file ? (
+        // Single file node
+        <li key={node.file.slug}>
+          <a href={resolveRelative(fileData.slug!, node.file.slug!)} data-for={node.file.slug}>
+            {node.displayName}
+          </a>
+        </li>
+      ) : (
+        <li>
+          {node.name !== "" && (
+            // Node with entire folder
+            // Render svg button + folder name, then children
+            <div class="folder-container">
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="12"
+                height="12"
+                viewBox="5 8 14 8"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                class="folder-icon"
+              >
+                <polyline points="6 9 12 15 18 9"></polyline>
+              </svg>
+              {/* render <a> tag if folderBehavior is "link", otherwise render <button> with collapse click event */}
+              <div key={node.name} data-folderpath={folderPath}>
+                {folderBehavior === "link" ? (
+                  <a
+                    href={resolveRelative(fileData.slug!, folderPath as SimpleSlug)}
+                    data-for={node.name}
+                    class="folder-title"
+                  >
+                    {node.displayName}
+                  </a>
+                ) : (
+                  <button class="folder-button">
+                    <span class="folder-title">{node.displayName}</span>
+                  </button>
+                )}
+              </div>
+            </div>
+          )}
+          {/* Recursively render children of folder */}
+          <div class={`folder-outer ${node.depth === 0 || isDefaultOpen ? "open" : ""}`}>
+            <ul
+              // Inline style for left folder paddings
+              style={{
+                paddingLeft: node.name !== "" ? "1.4rem" : "0",
+              }}
+              class="content"
+              data-folderul={folderPath}
+            >
+              {node.children.map((childNode, i) => (
+                <ExplorerNode
+                  node={childNode}
+                  key={i}
+                  opts={opts}
+                  fullPath={folderPath}
+                  fileData={fileData}
+                />
+              ))}
+            </ul>
+          </div>
+        </li>
+      )}
+    </>
+  )
+}

quartz/components/Footer.tsx

@@ -1,4 +1,4 @@
-import { QuartzComponentConstructor } from "./types"
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import style from "./styles/footer.scss"
 import { version } from "../../package.json"
 
@@ -7,11 +7,11 @@ interface Options {
 }
 
 export default ((opts?: Options) => {
-  function Footer() {
+  function Footer({ displayClass }: QuartzComponentProps) {
     const year = new Date().getFullYear()
     const links = opts?.links ?? []
     return (
-      <footer>
+      <footer class={`${displayClass ?? ""}`}>
         <hr />
         <p>
           Created with <a href="https://quartz.jzhao.xyz/">Quartz v{version}</a>, © {year}

quartz/components/Graph.tsx

@@ -1,7 +1,8 @@
-import { QuartzComponentConstructor } from "./types"
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 // @ts-ignore
 import script from "./scripts/graph.inline"
 import style from "./styles/graph.scss"
+import { classNames } from "../util/lang"
 
 export interface D3Config {
   drag: boolean
@@ -13,6 +14,8 @@ export interface D3Config {
   linkDistance: number
   fontSize: number
   opacityScale: number
+  removeTags: string[]
+  showTags: boolean
 }
 
 interface GraphOptions {
@@ -31,6 +34,8 @@ const defaultOptions: GraphOptions = {
     linkDistance: 30,
     fontSize: 0.6,
     opacityScale: 1,
+    showTags: true,
+    removeTags: [],
   },
   globalGraph: {
     drag: true,
@@ -42,15 +47,17 @@ const defaultOptions: GraphOptions = {
     linkDistance: 30,
     fontSize: 0.6,
     opacityScale: 1,
+    showTags: true,
+    removeTags: [],
   },
 }
 
 export default ((opts?: GraphOptions) => {
-  function Graph() {
+  function Graph({ displayClass }: QuartzComponentProps) {
-    const localGraph = { ...opts?.localGraph, ...defaultOptions.localGraph }
+    const localGraph = { ...defaultOptions.localGraph, ...opts?.localGraph }
-    const globalGraph = { ...opts?.globalGraph, ...defaultOptions.globalGraph }
+    const globalGraph = { ...defaultOptions.globalGraph, ...opts?.globalGraph }
     return (
-      <div class="graph">
+      <div class={classNames(displayClass, "graph")}>
         <h3>Graph View</h3>
         <div class="graph-outer">
           <div id="graph-container" data-cfg={JSON.stringify(localGraph)}></div>

quartz/components/Head.tsx

@@ -1,4 +1,4 @@
-import { joinSegments, pathToRoot } from "../util/path"
+import { FullSlug, _stripSlashes, joinSegments, pathToRoot } from "../util/path"
 import { JSResourceToScriptElement } from "../util/resources"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 
@@ -7,7 +7,11 @@ export default (() => {
     const title = fileData.frontmatter?.title ?? "Untitled"
     const description = fileData.description?.trim() ?? "No description provided"
     const { css, js } = externalResources
-    const baseDir = pathToRoot(fileData.slug!)
+
+    const url = new URL(`https://${cfg.baseUrl ?? "example.com"}`)
+    const path = url.pathname as FullSlug
+    const baseDir = fileData.slug === "404" ? path : pathToRoot(fileData.slug!)
+
     const iconPath = joinSegments(baseDir, "static/icon.png")
     const ogImagePath = `https://${cfg.baseUrl}/static/og-image.png`
 

quartz/components/PageList.tsx

@@ -1,12 +1,16 @@
 import { FullSlug, resolveRelative } from "../util/path"
 import { QuartzPluginData } from "../plugins/vfile"
-import { Date } from "./Date"
+import { Date, getDate } from "./Date"
 import { QuartzComponentProps } from "./types"
+import { GlobalConfiguration } from "../cfg"
 
-export function byDateAndAlphabetical(f1: QuartzPluginData, f2: QuartzPluginData): number {
+export function byDateAndAlphabetical(
+  cfg: GlobalConfiguration,
+): (f1: QuartzPluginData, f2: QuartzPluginData) => number {
+  return (f1, f2) => {
     if (f1.dates && f2.dates) {
-    // sort descending by last modified
+      // sort descending
-    return f2.dates.modified.getTime() - f1.dates.modified.getTime()
+      return getDate(cfg, f2)!.getTime() - getDate(cfg, f1)!.getTime()
     } else if (f1.dates && !f2.dates) {
       // prioritize files with dates
       return -1
@@ -19,13 +23,14 @@ export function byDateAndAlphabetical(f1: QuartzPluginData, f2: QuartzPluginData
     const f2Title = f2.frontmatter?.title.toLowerCase() ?? ""
     return f1Title.localeCompare(f2Title)
   }
+}
 
 type Props = {
   limit?: number
 } & QuartzComponentProps
 
-export function PageList({ fileData, allFiles, limit }: Props) {
+export function PageList({ cfg, fileData, allFiles, limit }: Props) {
-  let list = allFiles.sort(byDateAndAlphabetical)
+  let list = allFiles.sort(byDateAndAlphabetical(cfg))
   if (limit) {
     list = list.slice(0, limit)
   }
@@ -41,7 +46,7 @@ export function PageList({ fileData, allFiles, limit }: Props) {
             <div class="section">
               {page.dates && (
                 <p class="meta">
-                  <Date date={page.dates.modified} />
+                  <Date date={getDate(cfg, page)!} locale={cfg.locale} />
                 </p>
               )}
               <div class="desc">

quartz/components/PageTitle.tsx

@@ -1,11 +1,12 @@
 import { pathToRoot } from "../util/path"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
 
-function PageTitle({ fileData, cfg }: QuartzComponentProps) {
+function PageTitle({ fileData, cfg, displayClass }: QuartzComponentProps) {
   const title = cfg?.pageTitle ?? "Untitled Quartz"
   const baseDir = pathToRoot(fileData.slug!)
   return (
-    <h1 class="page-title">
+    <h1 class={classNames(displayClass, "page-title")}>
       <a href={baseDir}>{title}</a>
     </h1>
   )

quartz/components/RecentNotes.tsx

@@ -3,7 +3,9 @@ import { FullSlug, SimpleSlug, resolveRelative } from "../util/path"
 import { QuartzPluginData } from "../plugins/vfile"
 import { byDateAndAlphabetical } from "./PageList"
 import style from "./styles/recentNotes.scss"
-import { Date } from "./Date"
+import { Date, getDate } from "./Date"
+import { GlobalConfiguration } from "../cfg"
+import { classNames } from "../util/lang"
 
 interface Options {
   title: string
@@ -13,22 +15,21 @@ interface Options {
   sort: (f1: QuartzPluginData, f2: QuartzPluginData) => number
 }
 
-const defaultOptions: Options = {
+const defaultOptions = (cfg: GlobalConfiguration): Options => ({
   title: "Recent Notes",
   limit: 3,
   linkToMore: false,
   filter: () => true,
-  sort: byDateAndAlphabetical,
+  sort: byDateAndAlphabetical(cfg),
-}
+})
 
 export default ((userOpts?: Partial<Options>) => {
-  const opts = { ...defaultOptions, ...userOpts }
+  function RecentNotes({ allFiles, fileData, displayClass, cfg }: QuartzComponentProps) {
-  function RecentNotes(props: QuartzComponentProps) {
+    const opts = { ...defaultOptions(cfg), ...userOpts }
-    const { allFiles, fileData, displayClass } = props
     const pages = allFiles.filter(opts.filter).sort(opts.sort)
     const remaining = Math.max(0, pages.length - opts.limit)
     return (
-      <div class={`recent-notes ${displayClass}`}>
+      <div class={classNames(displayClass, "recent-notes")}>
         <h3>{opts.title}</h3>
         <ul class="recent-ul">
           {pages.slice(0, opts.limit).map((page) => {
@@ -47,7 +48,7 @@ export default ((userOpts?: Partial<Options>) => {
                   </div>
                   {page.dates && (
                     <p class="meta">
-                      <Date date={page.dates.modified} />
+                      <Date date={getDate(cfg, page)!} locale={cfg.locale} />
                     </p>
                   )}
                   <ul class="tags">

quartz/components/Search.tsx

@@ -1,12 +1,23 @@
-import { QuartzComponentConstructor } from "./types"
+import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import style from "./styles/search.scss"
 // @ts-ignore
 import script from "./scripts/search.inline"
+import { classNames } from "../util/lang"
+
+export interface SearchOptions {
+  enablePreview: boolean
+}
+
+const defaultOptions: SearchOptions = {
+  enablePreview: true,
+}
+
+export default ((userOpts?: Partial<SearchOptions>) => {
+  function Search({ displayClass }: QuartzComponentProps) {
+    const opts = { ...defaultOptions, ...userOpts }
 
-export default (() => {
-  function Search() {
     return (
-      <div class="search">
+      <div class={classNames(displayClass, "search")}>
         <div id="search-icon">
           <p>Search</p>
           <div></div>
@@ -35,7 +46,7 @@ export default (() => {
               aria-label="Search for something"
               placeholder="Search for something"
             />
-            <div id="results-container"></div>
+            <div id="search-layout" data-preview={opts.enablePreview}></div>
           </div>
         </div>
       </div>

quartz/components/Spacer.tsx

@@ -1,8 +1,8 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
 
 function Spacer({ displayClass }: QuartzComponentProps) {
-  const className = displayClass ? `spacer ${displayClass}` : "spacer"
+  return <div class={classNames(displayClass, "spacer")}></div>
-  return <div class={className}></div>
 }
 
 export default (() => Spacer) satisfies QuartzComponentConstructor

quartz/components/TableOfContents.tsx

@@ -1,6 +1,7 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import legacyStyle from "./styles/legacyToc.scss"
 import modernStyle from "./styles/toc.scss"
+import { classNames } from "../util/lang"
 
 // @ts-ignore
 import script from "./scripts/toc.inline"
@@ -19,8 +20,8 @@ function TableOfContents({ fileData, displayClass }: QuartzComponentProps) {
   }
 
   return (
-    <div class={`toc ${displayClass}`}>
+    <div class={classNames(displayClass, "toc")}>
-      <button type="button" id="toc">
+      <button type="button" id="toc" class={fileData.collapseToc ? "collapsed" : ""}>
         <h3>Table of Contents</h3>
         <svg
           xmlns="http://www.w3.org/2000/svg"
@@ -60,7 +61,7 @@ function LegacyTableOfContents({ fileData }: QuartzComponentProps) {
   }
 
   return (
-    <details id="toc" open>
+    <details id="toc" open={!fileData.collapseToc}>
       <summary>
         <h3>Table of Contents</h3>
       </summary>

quartz/components/TagList.tsx

@@ -1,12 +1,13 @@
 import { pathToRoot, slugTag } from "../util/path"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
+import { classNames } from "../util/lang"
 
-function TagList({ fileData }: QuartzComponentProps) {
+function TagList({ fileData, displayClass }: QuartzComponentProps) {
   const tags = fileData.frontmatter?.tags
   const baseDir = pathToRoot(fileData.slug!)
   if (tags && tags.length > 0) {
     return (
-      <ul class="tags">
+      <ul class={classNames(displayClass, "tags")}>
         {tags.map((tag) => {
           const display = `#${tag}`
           const linkDest = baseDir + `/tags/${slugTag(tag)}`
@@ -32,6 +33,12 @@ TagList.css = `
   padding-left: 0;
   gap: 0.4rem;
   margin: 1rem 0;
+  flex-wrap: wrap;
+  justify-self: end;
+}
+
+.section-li > .section > .tags {
+  justify-content: flex-end;
 }
   
 .tags > li {
@@ -41,10 +48,11 @@ TagList.css = `
   overflow-wrap: normal;
 }
 
-a.tag-link {
+a.internal.tag-link {
   border-radius: 8px;
   background-color: var(--highlight);
-  padding: 0.2rem 0.5rem;
+  padding: 0.2rem 0.4rem;
+  margin: 0 0.1rem;
 }
 `
 

quartz/components/index.ts

@@ -1,13 +1,15 @@
-import ArticleTitle from "./ArticleTitle"
 import Content from "./pages/Content"
 import TagContent from "./pages/TagContent"
 import FolderContent from "./pages/FolderContent"
+import NotFound from "./pages/404"
+import ArticleTitle from "./ArticleTitle"
 import Darkmode from "./Darkmode"
 import Head from "./Head"
 import PageTitle from "./PageTitle"
 import ContentMeta from "./ContentMeta"
 import Spacer from "./Spacer"
 import TableOfContents from "./TableOfContents"
+import Explorer from "./Explorer"
 import TagList from "./TagList"
 import Graph from "./Graph"
 import Backlinks from "./Backlinks"
@@ -16,6 +18,7 @@ import Footer from "./Footer"
 import DesktopOnly from "./DesktopOnly"
 import MobileOnly from "./MobileOnly"
 import RecentNotes from "./RecentNotes"
+import Breadcrumbs from "./Breadcrumbs"
 
 export {
   ArticleTitle,
@@ -28,6 +31,7 @@ export {
   ContentMeta,
   Spacer,
   TableOfContents,
+  Explorer,
   TagList,
   Graph,
   Backlinks,
@@ -36,4 +40,6 @@ export {
   DesktopOnly,
   MobileOnly,
   RecentNotes,
+  NotFound,
+  Breadcrumbs,
 }

quartz/components/pages/404.tsx

@@ -0,0 +1,12 @@
+import { QuartzComponentConstructor } from "../types"
+
+function NotFound() {
+  return (
+    <article class="popover-hint">
+      <h1>404</h1>
+      <p>Either this page is private or doesn't exist.</p>
+    </article>
+  )
+}
+
+export default (() => NotFound) satisfies QuartzComponentConstructor

quartz/components/pages/Content.tsx

@@ -1,11 +1,11 @@
+import { htmlToJsx } from "../../util/jsx"
 import { QuartzComponentConstructor, QuartzComponentProps } from "../types"
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime"
-import { toJsxRuntime } from "hast-util-to-jsx-runtime"
 
-function Content({ tree }: QuartzComponentProps) {
+function Content({ fileData, tree }: QuartzComponentProps) {
-  // @ts-ignore (preact makes it angry)
+  const content = htmlToJsx(fileData.filePath!, tree)
-  const content = toJsxRuntime(tree, { Fragment, jsx, jsxs, elementAttributeNameCase: "html" })
+  const classes: string[] = fileData.frontmatter?.cssclasses ?? []
-  return <article class="popover-hint">{content}</article>
+  const classString = ["popover-hint", ...classes].join(" ")
+  return <article class={classString}>{content}</article>
 }
 
 export default (() => Content) satisfies QuartzComponentConstructor

quartz/components/pages/FolderContent.tsx

@@ -1,12 +1,26 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "../types"
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime"
-import { toJsxRuntime } from "hast-util-to-jsx-runtime"
 import path from "path"
 
 import style from "../styles/listPage.scss"
 import { PageList } from "../PageList"
 import { _stripSlashes, simplifySlug } from "../../util/path"
 import { Root } from "hast"
+import { pluralize } from "../../util/lang"
+import { htmlToJsx } from "../../util/jsx"
+
+interface FolderContentOptions {
+  /**
+   * Whether to display number of folders
+   */
+  showFolderCount: boolean
+}
+
+const defaultOptions: FolderContentOptions = {
+  showFolderCount: true,
+}
+
+export default ((opts?: Partial<FolderContentOptions>) => {
+  const options: FolderContentOptions = { ...defaultOptions, ...opts }
 
   function FolderContent(props: QuartzComponentProps) {
     const { tree, fileData, allFiles } = props
@@ -19,7 +33,8 @@ function FolderContent(props: QuartzComponentProps) {
       const isDirectChild = fileParts.length === folderParts.length + 1
       return prefixed && isDirectChild
     })
-
+    const cssClasses: string[] = fileData.frontmatter?.cssclasses ?? []
+    const classes = ["popover-hint", ...cssClasses].join(" ")
     const listProps = {
       ...props,
       allFiles: allPagesInFolder,
@@ -28,19 +43,25 @@ function FolderContent(props: QuartzComponentProps) {
     const content =
       (tree as Root).children.length === 0
         ? fileData.description
-      : // @ts-ignore
+        : htmlToJsx(fileData.filePath!, tree)
-        toJsxRuntime(tree, { Fragment, jsx, jsxs, elementAttributeNameCase: "html" })
 
     return (
-    <div class="popover-hint">
+      <div class={classes}>
-      <article>{content}</article>
+        <article>
-      <p>{allPagesInFolder.length} items under this folder.</p>
+          <p>{content}</p>
+        </article>
+        <div class="page-listing">
+          {options.showFolderCount && (
+            <p>{pluralize(allPagesInFolder.length, "item")} under this folder.</p>
+          )}
           <div>
             <PageList {...listProps} />
           </div>
         </div>
+      </div>
     )
   }
 
   FolderContent.css = style + PageList.css
-export default (() => FolderContent) satisfies QuartzComponentConstructor
+  return FolderContent
+}) satisfies QuartzComponentConstructor

quartz/components/pages/TagContent.tsx

@@ -1,11 +1,11 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "../types"
-import { Fragment, jsx, jsxs } from "preact/jsx-runtime"
-import { toJsxRuntime } from "hast-util-to-jsx-runtime"
 import style from "../styles/listPage.scss"
 import { PageList } from "../PageList"
 import { FullSlug, getAllSegmentPrefixes, simplifySlug } from "../../util/path"
 import { QuartzPluginData } from "../../plugins/vfile"
 import { Root } from "hast"
+import { pluralize } from "../../util/lang"
+import { htmlToJsx } from "../../util/jsx"
 
 const numPages = 10
 function TagContent(props: QuartzComponentProps) {
@@ -25,19 +25,24 @@ function TagContent(props: QuartzComponentProps) {
   const content =
     (tree as Root).children.length === 0
       ? fileData.description
-      : // @ts-ignore
+      : htmlToJsx(fileData.filePath!, tree)
-        toJsxRuntime(tree, { Fragment, jsx, jsxs, elementAttributeNameCase: "html" })
+  const cssClasses: string[] = fileData.frontmatter?.cssclasses ?? []
-
+  const classes = ["popover-hint", ...cssClasses].join(" ")
-  if (tag === "") {
+  if (tag === "/") {
-    const tags = [...new Set(allFiles.flatMap((data) => data.frontmatter?.tags ?? []))]
+    const tags = [
+      ...new Set(
+        allFiles.flatMap((data) => data.frontmatter?.tags ?? []).flatMap(getAllSegmentPrefixes),
+      ),
+    ].sort((a, b) => a.localeCompare(b))
     const tagItemMap: Map<string, QuartzPluginData[]> = new Map()
     for (const tag of tags) {
       tagItemMap.set(tag, allPagesWithTag(tag))
     }
-
     return (
-      <div class="popover-hint">
+      <div class={classes}>
-        <article>{content}</article>
+        <article>
+          <p>{content}</p>
+        </article>
         <p>Found {tags.length} total tags.</p>
         <div>
           {tags.map((tag) => {
@@ -52,17 +57,19 @@ function TagContent(props: QuartzComponentProps) {
             return (
               <div>
                 <h2>
-                  <a class="internal tag-link" href={`./${tag}`}>
+                  <a class="internal tag-link" href={`../tags/${tag}`}>
                     #{tag}
                   </a>
                 </h2>
                 {content && <p>{content}</p>}
+                <div class="page-listing">
                   <p>
-                  {pages.length} items with this tag.{" "}
+                    {pluralize(pages.length, "item")} with this tag.{" "}
                     {pages.length > numPages && `Showing first ${numPages}.`}
                   </p>
                   <PageList limit={numPages} {...listProps} />
                 </div>
+              </div>
             )
           })}
         </div>
@@ -76,13 +83,15 @@ function TagContent(props: QuartzComponentProps) {
     }
 
     return (
-      <div class="popover-hint">
+      <div class={classes}>
         <article>{content}</article>
-        <p>{pages.length} items with this tag.</p>
+        <div class="page-listing">
+          <p>{pluralize(pages.length, "item")} with this tag.</p>
           <div>
             <PageList {...listProps} />
           </div>
         </div>
+      </div>
     )
   }
 }

quartz/components/renderPage.tsx

@@ -3,7 +3,10 @@ import { QuartzComponent, QuartzComponentProps } from "./types"
 import HeaderConstructor from "./Header"
 import BodyConstructor from "./Body"
 import { JSResourceToScriptElement, StaticResources } from "../util/resources"
-import { FullSlug, joinSegments, pathToRoot } from "../util/path"
+import { FullSlug, RelativeURL, joinSegments, normalizeHastElement } from "../util/path"
+import { visit } from "unist-util-visit"
+import { Root, Element, ElementContent } from "hast"
+import { QuartzPluginData } from "../plugins/vfile"
 
 interface RenderComponents {
   head: QuartzComponent
@@ -15,11 +18,12 @@ interface RenderComponents {
   footer: QuartzComponent
 }
 
-export function pageResources(slug: FullSlug, staticResources: StaticResources): StaticResources {
+export function pageResources(
-  const baseDir = pathToRoot(slug)
+  baseDir: FullSlug | RelativeURL,
-
+  staticResources: StaticResources,
+): StaticResources {
   const contentIndexPath = joinSegments(baseDir, "static/contentIndex.json")
-  const contentIndexScript = `const fetchData = fetch(\`${contentIndexPath}\`).then(data => data.json())`
+  const contentIndexScript = `const fetchData = fetch("${contentIndexPath}").then(data => data.json())`
 
   return {
     css: [joinSegments(baseDir, "index.css"), ...staticResources.css],
@@ -46,12 +50,121 @@ export function pageResources(slug: FullSlug, staticResources: StaticResources):
   }
 }
 
+let pageIndex: Map<FullSlug, QuartzPluginData> | undefined = undefined
+function getOrComputeFileIndex(allFiles: QuartzPluginData[]): Map<FullSlug, QuartzPluginData> {
+  if (!pageIndex) {
+    pageIndex = new Map()
+    for (const file of allFiles) {
+      pageIndex.set(file.slug!, file)
+    }
+  }
+
+  return pageIndex
+}
+
 export function renderPage(
   slug: FullSlug,
   componentData: QuartzComponentProps,
   components: RenderComponents,
   pageResources: StaticResources,
 ): string {
+  // process transcludes in componentData
+  visit(componentData.tree as Root, "element", (node, _index, _parent) => {
+    if (node.tagName === "blockquote") {
+      const classNames = (node.properties?.className ?? []) as string[]
+      if (classNames.includes("transclude")) {
+        const inner = node.children[0] as Element
+        const transcludeTarget = inner.properties["data-slug"] as FullSlug
+        const page = getOrComputeFileIndex(componentData.allFiles).get(transcludeTarget)
+        if (!page) {
+          return
+        }
+
+        let blockRef = node.properties.dataBlock as string | undefined
+        if (blockRef?.startsWith("#^")) {
+          // block transclude
+          blockRef = blockRef.slice("#^".length)
+          let blockNode = page.blocks?.[blockRef]
+          if (blockNode) {
+            if (blockNode.tagName === "li") {
+              blockNode = {
+                type: "element",
+                tagName: "ul",
+                properties: {},
+                children: [blockNode],
+              }
+            }
+
+            node.children = [
+              normalizeHastElement(blockNode, slug, transcludeTarget),
+              {
+                type: "element",
+                tagName: "a",
+                properties: { href: inner.properties?.href, class: ["internal"] },
+                children: [{ type: "text", value: `Link to original` }],
+              },
+            ]
+          }
+        } else if (blockRef?.startsWith("#") && page.htmlAst) {
+          // header transclude
+          blockRef = blockRef.slice(1)
+          let startIdx = undefined
+          let endIdx = undefined
+          for (const [i, el] of page.htmlAst.children.entries()) {
+            if (el.type === "element" && el.tagName.match(/h[1-6]/)) {
+              if (endIdx) {
+                break
+              }
+
+              if (startIdx !== undefined) {
+                endIdx = i
+              } else if (el.properties?.id === blockRef) {
+                startIdx = i
+              }
+            }
+          }
+
+          if (startIdx === undefined) {
+            return
+          }
+
+          node.children = [
+            ...(page.htmlAst.children.slice(startIdx, endIdx) as ElementContent[]).map((child) =>
+              normalizeHastElement(child as Element, slug, transcludeTarget),
+            ),
+            {
+              type: "element",
+              tagName: "a",
+              properties: { href: inner.properties?.href, class: ["internal"] },
+              children: [{ type: "text", value: `Link to original` }],
+            },
+          ]
+        } else if (page.htmlAst) {
+          // page transclude
+          node.children = [
+            {
+              type: "element",
+              tagName: "h1",
+              properties: {},
+              children: [
+                { type: "text", value: page.frontmatter?.title ?? `Transclude of ${page.slug}` },
+              ],
+            },
+            ...(page.htmlAst.children as ElementContent[]).map((child) =>
+              normalizeHastElement(child as Element, slug, transcludeTarget),
+            ),
+            {
+              type: "element",
+              tagName: "a",
+              properties: { href: inner.properties?.href, class: ["internal"] },
+              children: [{ type: "text", value: `Link to original` }],
+            },
+          ]
+        }
+      }
+    }
+  })
+
   const {
     head: Head,
     header,

quartz/components/scripts/darkmode.inline.ts

@@ -2,15 +2,19 @@ const userPref = window.matchMedia("(prefers-color-scheme: light)").matches ? "l
 const currentTheme = localStorage.getItem("theme") ?? userPref
 document.documentElement.setAttribute("saved-theme", currentTheme)
 
+const emitThemeChangeEvent = (theme: "light" | "dark") => {
+  const event: CustomEventMap["themechange"] = new CustomEvent("themechange", {
+    detail: { theme },
+  })
+  document.dispatchEvent(event)
+}
+
 document.addEventListener("nav", () => {
   const switchTheme = (e: any) => {
-    if (e.target.checked) {
+    const newTheme = e.target.checked ? "dark" : "light"
-      document.documentElement.setAttribute("saved-theme", "dark")
+    document.documentElement.setAttribute("saved-theme", newTheme)
-      localStorage.setItem("theme", "dark")
+    localStorage.setItem("theme", newTheme)
-    } else {
+    emitThemeChangeEvent(newTheme)
-      document.documentElement.setAttribute("saved-theme", "light")
-      localStorage.setItem("theme", "light")
-    }
   }
 
   // Darkmode toggle
@@ -20,4 +24,14 @@ document.addEventListener("nav", () => {
   if (currentTheme === "dark") {
     toggleSwitch.checked = true
   }
+
+  // Listen for changes in prefers-color-scheme
+  const colorSchemeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)")
+  colorSchemeMediaQuery.addEventListener("change", (e) => {
+    const newTheme = e.matches ? "dark" : "light"
+    document.documentElement.setAttribute("saved-theme", newTheme)
+    localStorage.setItem("theme", newTheme)
+    toggleSwitch.checked = e.matches
+    emitThemeChangeEvent(newTheme)
+  })
 })

quartz/components/scripts/explorer.inline.ts

@@ -0,0 +1,132 @@
+import { FolderState } from "../ExplorerNode"
+
+type MaybeHTMLElement = HTMLElement | undefined
+let currentExplorerState: FolderState[]
+const observer = new IntersectionObserver((entries) => {
+  // If last element is observed, remove gradient of "overflow" class so element is visible
+  const explorerUl = document.getElementById("explorer-ul")
+  if (!explorerUl) return
+  for (const entry of entries) {
+    if (entry.isIntersecting) {
+      explorerUl.classList.add("no-background")
+    } else {
+      explorerUl.classList.remove("no-background")
+    }
+  }
+})
+
+function toggleExplorer(this: HTMLElement) {
+  this.classList.toggle("collapsed")
+  const content = this.nextElementSibling as MaybeHTMLElement
+  if (!content) return
+
+  content.classList.toggle("collapsed")
+  content.style.maxHeight = content.style.maxHeight === "0px" ? content.scrollHeight + "px" : "0px"
+}
+
+function toggleFolder(evt: MouseEvent) {
+  evt.stopPropagation()
+  const target = evt.target as MaybeHTMLElement
+  if (!target) return
+
+  const isSvg = target.nodeName === "svg"
+  const childFolderContainer = (
+    isSvg
+      ? target.parentElement?.nextSibling
+      : target.parentElement?.parentElement?.nextElementSibling
+  ) as MaybeHTMLElement
+  const currentFolderParent = (
+    isSvg ? target.nextElementSibling : target.parentElement
+  ) as MaybeHTMLElement
+  if (!(childFolderContainer && currentFolderParent)) return
+
+  childFolderContainer.classList.toggle("open")
+  const isCollapsed = childFolderContainer.classList.contains("open")
+  setFolderState(childFolderContainer, !isCollapsed)
+  const fullFolderPath = currentFolderParent.dataset.folderpath as string
+  toggleCollapsedByPath(currentExplorerState, fullFolderPath)
+  const stringifiedFileTree = JSON.stringify(currentExplorerState)
+  localStorage.setItem("fileTree", stringifiedFileTree)
+}
+
+function setupExplorer() {
+  const explorer = document.getElementById("explorer")
+  if (!explorer) return
+
+  if (explorer.dataset.behavior === "collapse") {
+    for (const item of document.getElementsByClassName(
+      "folder-button",
+    ) as HTMLCollectionOf<HTMLElement>) {
+      item.removeEventListener("click", toggleFolder)
+      item.addEventListener("click", toggleFolder)
+    }
+  }
+
+  explorer.removeEventListener("click", toggleExplorer)
+  explorer.addEventListener("click", toggleExplorer)
+
+  // Set up click handlers for each folder (click handler on folder "icon")
+  for (const item of document.getElementsByClassName(
+    "folder-icon",
+  ) as HTMLCollectionOf<HTMLElement>) {
+    item.removeEventListener("click", toggleFolder)
+    item.addEventListener("click", toggleFolder)
+  }
+
+  // Get folder state from local storage
+  const storageTree = localStorage.getItem("fileTree")
+  const useSavedFolderState = explorer?.dataset.savestate === "true"
+  const oldExplorerState: FolderState[] =
+    storageTree && useSavedFolderState ? JSON.parse(storageTree) : []
+  const oldIndex = new Map(oldExplorerState.map((entry) => [entry.path, entry.collapsed]))
+  const newExplorerState: FolderState[] = explorer.dataset.tree
+    ? JSON.parse(explorer.dataset.tree)
+    : []
+  currentExplorerState = []
+  for (const { path, collapsed } of newExplorerState) {
+    currentExplorerState.push({ path, collapsed: oldIndex.get(path) ?? collapsed })
+  }
+
+  currentExplorerState.map((folderState) => {
+    const folderLi = document.querySelector(
+      `[data-folderpath='${folderState.path}']`,
+    ) as MaybeHTMLElement
+    const folderUl = folderLi?.parentElement?.nextElementSibling as MaybeHTMLElement
+    if (folderUl) {
+      setFolderState(folderUl, folderState.collapsed)
+    }
+  })
+}
+
+window.addEventListener("resize", setupExplorer)
+document.addEventListener("nav", () => {
+  setupExplorer()
+  observer.disconnect()
+
+  // select pseudo element at end of list
+  const lastItem = document.getElementById("explorer-end")
+  if (lastItem) {
+    observer.observe(lastItem)
+  }
+})
+
+/**
+ * Toggles the state of a given folder
+ * @param folderElement <div class="folder-outer"> Element of folder (parent)
+ * @param collapsed if folder should be set to collapsed or not
+ */
+function setFolderState(folderElement: HTMLElement, collapsed: boolean) {
+  return collapsed ? folderElement.classList.remove("open") : folderElement.classList.add("open")
+}
+
+/**
+ * Toggles visibility of a folder
+ * @param array array of FolderState (`fileTree`, either get from local storage or data attribute)
+ * @param path path to folder (e.g. 'advanced/more/more2')
+ */
+function toggleCollapsedByPath(array: FolderState[], path: string) {
+  const entry = array.find((item) => item.path === path)
+  if (entry) {
+    entry.collapsed = !entry.collapsed
+  }
+}

quartz/components/scripts/graph.inline.ts

@@ -1,4 +1,4 @@
-import type { ContentDetails } from "../../plugins/emitters/contentIndex"
+import type { ContentDetails, ContentIndex } from "../../plugins/emitters/contentIndex"
 import * as d3 from "d3"
 import { registerEscapeHandler, removeAllChildren } from "./util"
 import { FullSlug, SimpleSlug, getFullSlug, resolveRelative, simplifySlug } from "../../util/path"
@@ -42,17 +42,38 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
     linkDistance,
     fontSize,
     opacityScale,
+    removeTags,
+    showTags,
   } = JSON.parse(graph.dataset["cfg"]!)
 
-  const data = await fetchData
+  const data: Map<SimpleSlug, ContentDetails> = new Map(
-
+    Object.entries<ContentDetails>(await fetchData).map(([k, v]) => [
+      simplifySlug(k as FullSlug),
+      v,
+    ]),
+  )
   const links: LinkData[] = []
-  for (const [src, details] of Object.entries<ContentDetails>(data)) {
+  const tags: SimpleSlug[] = []
-    const source = simplifySlug(src as FullSlug)
+
+  const validLinks = new Set(data.keys())
+  for (const [source, details] of data.entries()) {
     const outgoing = details.links ?? []
+
     for (const dest of outgoing) {
-      if (dest in data) {
+      if (validLinks.has(dest)) {
-        links.push({ source, target: dest })
+        links.push({ source: source, target: dest })
+      }
+    }
+
+    if (showTags) {
+      const localTags = details.tags
+        .filter((tag) => !removeTags.includes(tag))
+        .map((tag) => simplifySlug(("tags/" + tag) as FullSlug))
+
+      tags.push(...localTags.filter((tag) => !tags.includes(tag)))
+
+      for (const tag of localTags) {
+        links.push({ source: source, target: tag })
       }
     }
   }
@@ -74,15 +95,19 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
       }
     }
   } else {
-    Object.keys(data).forEach((id) => neighbourhood.add(simplifySlug(id as FullSlug)))
+    validLinks.forEach((id) => neighbourhood.add(id))
+    if (showTags) tags.forEach((tag) => neighbourhood.add(tag))
   }
 
   const graphData: { nodes: NodeData[]; links: LinkData[] } = {
-    nodes: [...neighbourhood].map((url) => ({
+    nodes: [...neighbourhood].map((url) => {
+      const text = url.startsWith("tags/") ? "#" + url.substring(5) : data.get(url)?.title ?? url
+      return {
         id: url,
-      text: data[url]?.title ?? url,
+        text: text,
-      tags: data[url]?.tags ?? [],
+        tags: data.get(url)?.tags ?? [],
-    })),
+      }
+    }),
     links: links.filter((l) => neighbourhood.has(l.source) && neighbourhood.has(l.target)),
   }
 
@@ -126,7 +151,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
     const isCurrent = d.id === slug
     if (isCurrent) {
       return "var(--secondary)"
-    } else if (visited.has(d.id)) {
+    } else if (visited.has(d.id) || d.id.startsWith("tags/")) {
       return "var(--tertiary)"
     } else {
       return "var(--gray)"
@@ -177,7 +202,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
       window.spaNavigate(new URL(targ, window.location.toString()))
     })
     .on("mouseover", function (_, d) {
-      const neighbours: SimpleSlug[] = data[fullSlug].links ?? []
+      const neighbours: SimpleSlug[] = data.get(slug)?.links ?? []
       const neighbourNodes = d3
         .selectAll<HTMLElement, NodeData>(".node")
         .filter((d) => neighbours.includes(d.id))
@@ -230,9 +255,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
     .attr("dx", 0)
     .attr("dy", (d) => -nodeRadius(d) + "px")
     .attr("text-anchor", "middle")
-    .text(
+    .text((d) => d.text)
-      (d) => data[d.id]?.title || (d.id.charAt(1).toUpperCase() + d.id.slice(2)).replace("-", " "),
-    )
     .style("opacity", (opacityScale - 1) / 3.75)
     .style("pointer-events", "none")
     .style("font-size", fontSize + "em")
@@ -296,8 +319,8 @@ function renderGlobalGraph() {
   registerEscapeHandler(container, hideGlobalGraph)
 }
 
-document.addEventListener("nav", async (e: unknown) => {
+document.addEventListener("nav", async (e: CustomEventMap["nav"]) => {
-  const slug = (e as CustomEventMap["nav"]).detail.url
+  const slug = e.detail.url
   addToVisited(slug)
   await renderGraph("graph-container", slug)
 

quartz/components/scripts/plausible.inline.ts

@@ -1,3 +0,0 @@
-import Plausible from "plausible-tracker"
-const { trackPageview } = Plausible()
-document.addEventListener("nav", () => trackPageview())

quartz/components/scripts/popover.inline.ts

@@ -1,16 +1,5 @@
 import { computePosition, flip, inline, shift } from "@floating-ui/dom"
-
+import { normalizeRelativeURLs } from "../../util/path"
-// from micromorph/src/utils.ts
-// https://github.com/natemoo-re/micromorph/blob/main/src/utils.ts#L5
-export function normalizeRelativeURLs(el: Element | Document, base: string | URL) {
-  const update = (el: Element, attr: string, base: string | URL) => {
-    el.setAttribute(attr, new URL(el.getAttribute(attr)!, base).pathname)
-  }
-
-  el.querySelectorAll('[href^="./"], [href^="../"]').forEach((item) => update(item, "href", base))
-
-  el.querySelectorAll('[src^="./"], [src^="../"]').forEach((item) => update(item, "src", base))
-}
 
 const p = new DOMParser()
 async function mouseEnterHandler(
@@ -18,6 +7,10 @@ async function mouseEnterHandler(
   { clientX, clientY }: { clientX: number; clientY: number },
 ) {
   const link = this
+  if (link.dataset.noPopover === "true") {
+    return
+  }
+
   async function setPosition(popoverElement: HTMLElement) {
     const { x, y } = await computePosition(link, popoverElement, {
       middleware: [inline({ x: clientX, y: clientY }), shift(), flip()],
@@ -28,8 +21,11 @@ async function mouseEnterHandler(
     })
   }
 
+  const hasAlreadyBeenFetched = () =>
+    [...link.children].some((child) => child.classList.contains("popover"))
+
   // dont refetch if there's already a popover
-  if ([...link.children].some((child) => child.classList.contains("popover"))) {
+  if (hasAlreadyBeenFetched()) {
     return setPosition(link.lastChild as HTMLElement)
   }
 
@@ -40,8 +36,6 @@ async function mouseEnterHandler(
   const hash = targetUrl.hash
   targetUrl.hash = ""
   targetUrl.search = ""
-  // prevent hover of the same page
-  if (thisUrl.toString() === targetUrl.toString()) return
 
   const contents = await fetch(`${targetUrl}`)
     .then((res) => res.text())
@@ -49,6 +43,11 @@ async function mouseEnterHandler(
       console.error(err)
     })
 
+  // bailout if another popover exists
+  if (hasAlreadyBeenFetched()) {
+    return
+  }
+
   if (!contents) return
   const html = p.parseFromString(contents, "text/html")
   normalizeRelativeURLs(html, targetUrl)

quartz/components/scripts/search.inline.ts

@@ -1,19 +1,27 @@
-import { Document } from "flexsearch"
+import FlexSearch from "flexsearch"
 import { ContentDetails } from "../../plugins/emitters/contentIndex"
 import { registerEscapeHandler, removeAllChildren } from "./util"
-import { FullSlug, getFullSlug, resolveRelative, simplifySlug } from "../../util/path"
+import { FullSlug, normalizeRelativeURLs, resolveRelative } from "../../util/path"
 
 interface Item {
   id: number
   slug: FullSlug
   title: string
   content: string
+  tags: string[]
 }
 
-let index: Document<Item> | undefined = undefined
+let index: FlexSearch.Document<Item> | undefined = undefined
+
+// Can be expanded with things like "term" in the future
+type SearchType = "basic" | "tags"
+
+// Current searchType
+let searchType: SearchType = "basic"
 
 const contextWindowWords = 30
-const numSearchResults = 5
+const numSearchResults = 8
+const numTagResults = 5
 function highlight(searchTerm: string, text: string, trim?: boolean) {
   // try to highlight longest tokens first
   const tokenizedTerms = searchTerm
@@ -27,12 +35,12 @@ function highlight(searchTerm: string, text: string, trim?: boolean) {
   if (trim) {
     const includesCheck = (tok: string) =>
       tokenizedTerms.some((term) => tok.toLowerCase().startsWith(term.toLowerCase()))
-    const occurencesIndices = tokenizedText.map(includesCheck)
+    const occurrencesIndices = tokenizedText.map(includesCheck)
 
     let bestSum = 0
     let bestIndex = 0
     for (let i = 0; i < Math.max(tokenizedText.length - contextWindowWords, 0); i++) {
-      const window = occurencesIndices.slice(i, i + contextWindowWords)
+      const window = occurrencesIndices.slice(i, i + contextWindowWords)
       const windowSum = window.reduce((total, cur) => total + (cur ? 1 : 0), 0)
       if (windowSum >= bestSum) {
         bestSum = windowSum
@@ -63,18 +71,43 @@ function highlight(searchTerm: string, text: string, trim?: boolean) {
   }`
 }
 
+const p = new DOMParser()
 const encoder = (str: string) => str.toLowerCase().split(/([^a-z]|[^\x00-\x7F])/)
-document.addEventListener("nav", async (e: unknown) => {
+let prevShortcutHandler: ((e: HTMLElementEventMap["keydown"]) => void) | undefined = undefined
-  const currentSlug = (e as CustomEventMap["nav"]).detail.url
+
+const fetchContentCache: Map<FullSlug, Element[]> = new Map()
+
+document.addEventListener("nav", async (e: CustomEventMap["nav"]) => {
+  const currentSlug = e.detail.url
 
   const data = await fetchData
   const container = document.getElementById("search-container")
   const sidebar = container?.closest(".sidebar") as HTMLElement
   const searchIcon = document.getElementById("search-icon")
   const searchBar = document.getElementById("search-bar") as HTMLInputElement | null
-  const results = document.getElementById("results-container")
+  const searchLayout = document.getElementById("search-layout")
   const idDataMap = Object.keys(data) as FullSlug[]
 
+  const appendLayout = (el: HTMLElement) => {
+    if (searchLayout?.querySelector(`#${el.id}`) === null) {
+      searchLayout?.appendChild(el)
+    }
+  }
+
+  const enablePreview = searchLayout?.dataset?.preview === "true"
+  let preview: HTMLDivElement | undefined = undefined
+  const results = document.createElement("div")
+  results.id = "results-container"
+  results.style.flexBasis = enablePreview ? "30%" : "100%"
+  appendLayout(results)
+
+  if (enablePreview) {
+    preview = document.createElement("div")
+    preview.id = "preview-container"
+    preview.style.flexBasis = "70%"
+    appendLayout(preview)
+  }
+
   function hideSearch() {
     container?.classList.remove("active")
     if (searchBar) {
@@ -86,9 +119,15 @@ document.addEventListener("nav", async (e: unknown) => {
     if (results) {
       removeAllChildren(results)
     }
+    if (preview) {
+      removeAllChildren(preview)
     }
 
-  function showSearch() {
+    searchType = "basic" // reset search type after closing
+  }
+
+  function showSearch(searchTypeNew: SearchType) {
+    searchType = searchTypeNew
     if (sidebar) {
       sidebar.style.zIndex = "1"
     }
@@ -96,17 +135,91 @@ document.addEventListener("nav", async (e: unknown) => {
     searchBar?.focus()
   }
 
-  function shortcutHandler(e: HTMLElementEventMap["keydown"]) {
+  async function shortcutHandler(e: HTMLElementEventMap["keydown"]) {
-    if (e.key === "k" && (e.ctrlKey || e.metaKey)) {
+    if (e.key === "k" && (e.ctrlKey || e.metaKey) && !e.shiftKey) {
       e.preventDefault()
       const searchBarOpen = container?.classList.contains("active")
-      searchBarOpen ? hideSearch() : showSearch()
+      searchBarOpen ? hideSearch() : showSearch("basic")
-    } else if (e.key === "Enter") {
+    } else if (e.shiftKey && (e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k") {
-      const anchor = document.getElementsByClassName("result-card")[0] as HTMLInputElement | null
+      // Hotkey to open tag search
-      if (anchor) {
+      e.preventDefault()
-        anchor.click()
+      const searchBarOpen = container?.classList.contains("active")
+      searchBarOpen ? hideSearch() : showSearch("tags")
+
+      // add "#" prefix for tag search
+      if (searchBar) searchBar.value = "#"
+    }
+
+    const resultCards = document.getElementsByClassName("result-card")
+
+    // If search is active, then we will render the first result and display accordingly
+    if (!container?.classList.contains("active")) return
+    else if (results?.contains(document.activeElement)) {
+      const active = document.activeElement as HTMLInputElement
+      await displayPreview(active)
+      if (e.key === "Enter") {
+        active.click()
+      }
+    } else {
+      const anchor = resultCards[0] as HTMLInputElement | null
+      await displayPreview(anchor)
+      if (e.key === "Enter") {
+        anchor?.click()
       }
     }
+
+    if (e.key === "ArrowUp" || (e.shiftKey && e.key === "Tab")) {
+      e.preventDefault()
+      if (results?.contains(document.activeElement)) {
+        // If an element in results-container already has focus, focus previous one
+        const currentResult = document.activeElement as HTMLInputElement | null
+        const prevResult = currentResult?.previousElementSibling as HTMLInputElement | null
+        currentResult?.classList.remove("focus")
+        await displayPreview(prevResult)
+        prevResult?.focus()
+      }
+    } else if (e.key === "ArrowDown" || e.key === "Tab") {
+      e.preventDefault()
+      // The results should already been focused, so we need to find the next one.
+      // The activeElement is the search bar, so we need to find the first result and focus it.
+      if (!results?.contains(document.activeElement)) {
+        const firstResult = resultCards[0] as HTMLInputElement | null
+        const secondResult = firstResult?.nextElementSibling as HTMLInputElement | null
+        firstResult?.classList.remove("focus")
+        await displayPreview(secondResult)
+        secondResult?.focus()
+      } else {
+        // If an element in results-container already has focus, focus next one
+        const active = document.activeElement as HTMLInputElement | null
+        active?.classList.remove("focus")
+        const nextResult = active?.nextElementSibling as HTMLInputElement | null
+        await displayPreview(nextResult)
+        nextResult?.focus()
+      }
+    }
+  }
+
+  function trimContent(content: string) {
+    // works without escaping html like in `description.ts`
+    const sentences = content.replace(/\s+/g, " ").split(".")
+    let finalDesc = ""
+    let sentenceIdx = 0
+
+    // Roughly estimate characters by (words * 5). Matches description length in `description.ts`.
+    const len = contextWindowWords * 5
+    while (finalDesc.length < len) {
+      const sentence = sentences[sentenceIdx]
+      if (!sentence) break
+      finalDesc += sentence + "."
+      sentenceIdx++
+    }
+
+    // If more content would be available, indicate it by finishing with "..."
+    if (finalDesc.length < content.length) {
+      finalDesc += ".."
+    }
+
+    return finalDesc
   }
 
   const formatForDisplay = (term: string, id: number) => {
@@ -114,80 +227,243 @@ document.addEventListener("nav", async (e: unknown) => {
     return {
       id,
       slug,
-      title: highlight(term, data[slug].title ?? ""),
+      title: searchType === "tags" ? data[slug].title : highlight(term, data[slug].title ?? ""),
-      content: highlight(term, data[slug].content ?? "", true),
+      // if searchType is tag, display context from start of file and trim, otherwise use regular highlight
+      content:
+        searchType === "tags"
+          ? trimContent(data[slug].content)
+          : highlight(term, data[slug].content ?? "", true),
+      tags: highlightTags(term, data[slug].tags),
     }
   }
 
-  const resultToHTML = ({ slug, title, content }: Item) => {
+  function highlightTags(term: string, tags: string[]) {
-    const button = document.createElement("button")
+    if (tags && searchType === "tags") {
-    button.classList.add("result-card")
+      // Find matching tags
-    button.id = slug
+      const termLower = term.toLowerCase()
-    button.innerHTML = `<h3>${title}</h3><p>${content}</p>`
+      let matching = tags.filter((str) => str.includes(termLower))
-    button.addEventListener("click", () => {
+
-      const targ = resolveRelative(currentSlug, slug)
+      // Subtract matching from original tags, then push difference
-      window.spaNavigate(new URL(targ, window.location.toString()))
+      if (matching.length > 0) {
+        let difference = tags.filter((x) => !matching.includes(x))
+
+        // Convert to html (cant be done later as matches/term dont get passed to `resultToHTML`)
+        matching = matching.map((tag) => `<li><p class="match-tag">#${tag}</p></li>`)
+        difference = difference.map((tag) => `<li><p>#${tag}</p></li>`)
+        matching.push(...difference)
+      }
+
+      // Only allow max of `numTagResults` in preview
+      if (tags.length > numTagResults) {
+        matching.splice(numTagResults)
+      }
+
+      return matching
+    } else {
+      return []
+    }
+  }
+
+  function resolveUrl(slug: FullSlug): URL {
+    return new URL(resolveRelative(currentSlug, slug), location.toString())
+  }
+
+  const resultToHTML = ({ slug, title, content, tags }: Item) => {
+    const htmlTags = tags.length > 0 ? `<ul>${tags.join("")}</ul>` : ``
+    const resultContent = enablePreview && window.innerWidth > 600 ? "" : `<p>${content}</p>`
+
+    const itemTile = document.createElement("a")
+    itemTile.classList.add("result-card")
+    Object.assign(itemTile, {
+      id: slug,
+      href: resolveUrl(slug).toString(),
+      innerHTML: `<h3>${title}</h3>${htmlTags}${resultContent}`,
     })
-    return button
+
+    async function onMouseEnter(ev: MouseEvent) {
+      // When search is active, the first element is in focus, so we need to remove focus if given target is not the first element
+      const firstEl = document.getElementsByClassName("result-card")[0] as HTMLAnchorElement | null
+      const target = ev.target as HTMLAnchorElement
+      if (firstEl !== target) {
+        firstEl?.classList.remove("focus")
+      }
+      target.classList.add("focus")
+      await displayPreview(target)
     }
 
-  function displayResults(finalResults: Item[]) {
+    async function onMouseLeave(ev: MouseEvent) {
+      const target = ev.target as HTMLAnchorElement
+      target.classList.remove("focus")
+    }
+
+    const events = [
+      ["mouseenter", onMouseEnter],
+      ["mouseleave", onMouseLeave],
+      [
+        "click",
+        (event: MouseEvent) => {
+          if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
+          hideSearch()
+        },
+      ],
+    ] as [keyof HTMLElementEventMap, (this: HTMLElement) => void][]
+
+    events.forEach(([event, handler]) => itemTile.addEventListener(event, handler))
+
+    return itemTile
+  }
+
+  async function displayResults(finalResults: Item[]) {
     if (!results) return
 
     removeAllChildren(results)
     if (finalResults.length === 0) {
-      results.innerHTML = `<button class="result-card">
+      results.innerHTML = `<a class="result-card">
                     <h3>No results.</h3>
                     <p>Try another search term?</p>
-                </button>`
+                </a>`
     } else {
       results.append(...finalResults.map(resultToHTML))
     }
+    // focus on first result, then also dispatch preview immediately
+    if (results?.firstElementChild) {
+      results?.firstElementChild?.classList.add("focus")
+      await displayPreview(results?.firstElementChild as HTMLElement)
+    }
+  }
+
+  async function fetchContent(slug: FullSlug): Promise<Element[]> {
+    if (fetchContentCache.has(slug)) {
+      return fetchContentCache.get(slug) as Element[]
+    }
+
+    const targetUrl = resolveUrl(slug).toString()
+    const contents = await fetch(targetUrl)
+      .then((res) => res.text())
+      .then((contents) => {
+        if (contents === undefined) {
+          throw new Error(`Could not fetch ${targetUrl}`)
+        }
+        const html = p.parseFromString(contents ?? "", "text/html")
+        normalizeRelativeURLs(html, targetUrl)
+        return [...html.getElementsByClassName("popover-hint")]
+      })
+
+    fetchContentCache.set(slug, contents)
+    return contents
+  }
+
+  async function displayPreview(el: HTMLElement | null) {
+    if (!searchLayout || !enablePreview || !el) return
+
+    const slug = el.id as FullSlug
+    el.classList.add("focus")
+
+    removeAllChildren(preview as HTMLElement)
+    const contentDetails = await fetchContent(slug)
+
+    const previewInner = document.createElement("div")
+    previewInner.classList.add("preview-inner")
+    preview?.appendChild(previewInner)
+    contentDetails?.forEach((elt) => previewInner.appendChild(elt))
   }
 
   async function onType(e: HTMLElementEventMap["input"]) {
-    const term = (e.target as HTMLInputElement).value
+    let term = (e.target as HTMLInputElement).value
-    const searchResults = (await index?.searchAsync(term, numSearchResults)) ?? []
+    let searchResults: FlexSearch.SimpleDocumentSearchResultSetUnit[]
+
+    if (searchLayout) {
+      searchLayout.style.opacity = "1"
+    }
+
+    if (term.toLowerCase().startsWith("#")) {
+      searchType = "tags"
+    } else {
+      searchType = "basic"
+    }
+
+    switch (searchType) {
+      case "tags": {
+        term = term.substring(1)
+        searchResults =
+          (await index?.searchAsync({ query: term, limit: numSearchResults, index: ["tags"] })) ??
+          []
+        break
+      }
+      case "basic":
+      default: {
+        searchResults =
+          (await index?.searchAsync({
+            query: term,
+            limit: numSearchResults,
+            index: ["title", "content"],
+          })) ?? []
+      }
+    }
+
     const getByField = (field: string): number[] => {
       const results = searchResults.filter((x) => x.field === field)
       return results.length === 0 ? [] : ([...results[0].result] as number[])
     }
 
     // order titles ahead of content
-    const allIds: Set<number> = new Set([...getByField("title"), ...getByField("content")])
+    const allIds: Set<number> = new Set([
+      ...getByField("title"),
+      ...getByField("content"),
+      ...getByField("tags"),
+    ])
     const finalResults = [...allIds].map((id) => formatForDisplay(term, id))
-    displayResults(finalResults)
+    await displayResults(finalResults)
+  }
+
+  if (prevShortcutHandler) {
+    document.removeEventListener("keydown", prevShortcutHandler)
   }
 
-  document.removeEventListener("keydown", shortcutHandler)
   document.addEventListener("keydown", shortcutHandler)
-  searchIcon?.removeEventListener("click", showSearch)
+  prevShortcutHandler = shortcutHandler
-  searchIcon?.addEventListener("click", showSearch)
+  searchIcon?.removeEventListener("click", () => showSearch("basic"))
+  searchIcon?.addEventListener("click", () => showSearch("basic"))
   searchBar?.removeEventListener("input", onType)
   searchBar?.addEventListener("input", onType)
 
   // setup index if it hasn't been already
   if (!index) {
-    index = new Document({
+    index = new FlexSearch.Document({
-      cache: true,
       charset: "latin:extra",
-      optimize: true,
       encode: encoder,
       document: {
         id: "id",
         index: [
           {
             field: "title",
-            tokenize: "reverse",
+            tokenize: "forward",
           },
           {
             field: "content",
-            tokenize: "reverse",
+            tokenize: "forward",
+          },
+          {
+            field: "tags",
+            tokenize: "forward",
           },
         ],
       },
     })
 
+    fillDocument(index, data)
+  }
+
+  // register handlers
+  registerEscapeHandler(container, hideSearch)
+})
+
+/**
+ * Fills flexsearch document with data
+ * @param index index to fill
+ * @param data data to fill index with
+ */
+async function fillDocument(index: FlexSearch.Document<Item, false>, data: any) {
   let id = 0
   for (const [slug, fileData] of Object.entries<ContentDetails>(data)) {
     await index.addAsync(id, {
@@ -195,11 +471,8 @@ document.addEventListener("nav", async (e: unknown) => {
       slug: slug as FullSlug,
       title: fileData.title,
       content: fileData.content,
+      tags: fileData.tags,
     })
     id++
   }
 }
-
-  // register handlers
-  registerEscapeHandler(container, hideSearch)
-})

quartz/components/scripts/spa.inline.ts

@@ -1,9 +1,8 @@
 import micromorph from "micromorph"
-import { FullSlug, RelativeURL, getFullSlug } from "../../util/path"
+import { FullSlug, RelativeURL, getFullSlug, normalizeRelativeURLs } from "../../util/path"
 
 // adapted from `micromorph`
 // https://github.com/natemoo-re/micromorph
-
 const NODE_TYPE_ELEMENT = 1
 let announcer = document.createElement("route-announcer")
 const isElement = (target: EventTarget | null): target is Element =>
@@ -12,17 +11,21 @@ const isLocalUrl = (href: string) => {
   try {
     const url = new URL(href)
     if (window.location.origin === url.origin) {
-      if (url.pathname === window.location.pathname) {
-        return !url.hash
-      }
       return true
     }
   } catch (e) {}
   return false
 }
 
+const isSamePage = (url: URL): boolean => {
+  const sameOrigin = url.origin === window.location.origin
+  const samePath = url.pathname === window.location.pathname
+  return sameOrigin && samePath
+}
+
 const getOpts = ({ target }: Event): { url: URL; scroll?: boolean } | undefined => {
   if (!isElement(target)) return
+  if (target.attributes.getNamedItem("target")?.value === "_blank") return
   const a = target.closest("a")
   if (!a) return
   if ("routerIgnore" in a.dataset) return
@@ -40,7 +43,14 @@ let p: DOMParser
 async function navigate(url: URL, isBack: boolean = false) {
   p = p || new DOMParser()
   const contents = await fetch(`${url}`)
-    .then((res) => res.text())
+    .then((res) => {
+      const contentType = res.headers.get("content-type")
+      if (contentType?.startsWith("text/html")) {
+        return res.text()
+      } else {
+        window.location.assign(url)
+      }
+    })
     .catch(() => {
       window.location.assign(url)
     })
@@ -48,6 +58,8 @@ async function navigate(url: URL, isBack: boolean = false) {
   if (!contents) return
 
   const html = p.parseFromString(contents, "text/html")
+  normalizeRelativeURLs(html, url)
+
   let title = html.querySelector("title")?.textContent
   if (title) {
     document.title = title
@@ -67,7 +79,7 @@ async function navigate(url: URL, isBack: boolean = false) {
   // scroll into place and add history
   if (!isBack) {
     if (url.hash) {
-      const el = document.getElementById(url.hash.substring(1))
+      const el = document.getElementById(decodeURIComponent(url.hash.substring(1)))
       el?.scrollIntoView()
     } else {
       window.scrollTo({ top: 0 })
@@ -82,7 +94,9 @@ async function navigate(url: URL, isBack: boolean = false) {
 
   // delay setting the url until now
   // at this point everything is loaded so changing the url should resolve to the correct addresses
+  if (!isBack) {
     history.pushState({}, "", url)
+  }
   notifyNav(getFullSlug(window))
   delete announcer.dataset.persist
 }
@@ -93,8 +107,17 @@ function createRouter() {
   if (typeof window !== "undefined") {
     window.addEventListener("click", async (event) => {
       const { url } = getOpts(event) ?? {}
-      if (!url) return
+      // dont hijack behaviour, just let browser act normally
+      if (!url || event.ctrlKey || event.metaKey) return
       event.preventDefault()
+
+      if (isSamePage(url) && url.hash) {
+        const el = document.getElementById(decodeURIComponent(url.hash.substring(1)))
+        el?.scrollIntoView()
+        history.pushState({}, "", url)
+        return
+      }
+
       try {
         navigate(url, false)
       } catch (e) {
@@ -140,6 +163,7 @@ if (!customElements.get("route-announcer")) {
     style:
       "position: absolute; left: 0; top: 0; clip: rect(0 0 0 0); clip-path: inset(50%); overflow: hidden; white-space: nowrap; width: 1px; height: 1px",
   }
+
   customElements.define(
     "route-announcer",
     class RouteAnnouncer extends HTMLElement {

quartz/components/scripts/toc.inline.ts

@@ -16,7 +16,8 @@ const observer = new IntersectionObserver((entries) => {
 
 function toggleToc(this: HTMLElement) {
   this.classList.toggle("collapsed")
-  const content = this.nextElementSibling as HTMLElement
+  const content = this.nextElementSibling as HTMLElement | undefined
+  if (!content) return
   content.classList.toggle("collapsed")
   content.style.maxHeight = content.style.maxHeight === "0px" ? content.scrollHeight + "px" : "0px"
 }
@@ -24,8 +25,10 @@ function toggleToc(this: HTMLElement) {
 function setupToc() {
   const toc = document.getElementById("toc")
   if (toc) {
-    const content = toc.nextElementSibling as HTMLElement
+    const collapsed = toc.classList.contains("collapsed")
-    content.style.maxHeight = content.scrollHeight + "px"
+    const content = toc.nextElementSibling as HTMLElement | undefined
+    if (!content) return
+    content.style.maxHeight = collapsed ? "0px" : content.scrollHeight + "px"
     toc.removeEventListener("click", toggleToc)
     toc.addEventListener("click", toggleToc)
   }

quartz/components/styles/breadcrumbs.scss

@@ -0,0 +1,22 @@
+.breadcrumb-container {
+  margin: 0;
+  margin-top: 0.75rem;
+  padding: 0;
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.breadcrumb-element {
+  p {
+    margin: 0;
+    margin-left: 0.5rem;
+    padding: 0;
+    line-height: normal;
+  }
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+}

quartz/components/styles/clipboard.scss

@@ -4,13 +4,12 @@
   float: right;
   right: 0;
   padding: 0.4rem;
-  margin: -0.2rem 0.3rem;
+  margin: 0.3rem;
   color: var(--gray);
   border-color: var(--dark);
   background-color: var(--light);
   border: 1px solid;
   border-radius: 5px;
-  z-index: 1;
   opacity: 0;
   transition: 0.2s;
 

quartz/components/styles/darkmode.scss

@@ -21,6 +21,14 @@
   }
 }
 
+:root[saved-theme="dark"] {
+  color-scheme: dark;
+}
+
+:root[saved-theme="light"] {
+  color-scheme: light;
+}
+
 :root[saved-theme="dark"] .toggle ~ label {
   & > #dayIcon {
     opacity: 0;