Merge branch 'v4' into bak

2025-12-24 13:24:05 -06:00 · 2023-12-17 01:23:51 +08:00 · 2023-12-17 01:23:51 +08:00 · 0c92dd7b74
commit 0c92dd7b74
parent 998fa89027 ed9bd43d9f
32 changed files with 390 additions and 105 deletions
--- a/docs/features/breadcrumbs.md
+++ b/docs/features/breadcrumbs.md
@ -20,6 +20,7 @@ Component.Breadcrumbs({
  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, // wether to display the current page in the breadcrumbs
 })
 ```

--- a/docs/hosting.md
+++ b/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,12 +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
-
-Like Quartz 3, you can deploy the site generated by Quartz 4 via GitHub Pages.
-
 > [!warning]
-> 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, consider using [[#Cloudflare Pages]].
+> 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.
+
+## GitHub Pages

 In your local Quartz, create a new file `quartz/.github/workflows/deploy.yml`.

@ -93,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.
@ -167,9 +171,16 @@ Using `docs.example.com` is an example of a subdomain. They're a simple way of c
 4. Go to the Settings tab and then click Domains in the sidebar
 5. Enter your subdomain into the field and press Add

-## GitLab Pages
+## Netlify

-You can configure GitLab CI to build and deploy a Quartz 4 project.
+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`.

@ -192,8 +203,6 @@ build:
    - hash -r
    - npm ci
  script:
-    - npx prettier --write .
-    - npm run check
    - npx quartz build
  artifacts:
    paths:
@ -216,6 +225,6 @@ pages:
      - public
 ```

-When `.gitlab-ci.yaml` is commited, GitLab will build and deploy the website as a GitLab Page. You can find the url under `Deploy` -> `Pages` in the sidebar.
+When `.gitlab-ci.yaml` is commited, 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`.
--- a/docs/images/github-init-repo-options.png
+++ b/docs/images/github-init-repo-options.png
--- a/docs/images/github-quick-setup.png
+++ b/docs/images/github-quick-setup.png
--- a/docs/index.md
+++ b/docs/index.md
@ -2,7 +2,7 @@
 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

@ -19,7 +19,7 @@ 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
--- a/repository.md
+++ b/repository.md
@ -0,0 +1,35 @@
+---
+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
+# add your repository
+git remote add origin REMOTE-URL
+
+# track the main quartz repository for updates
+git remote add upstream https://github.com/jackyzha0/quartz.git
+```
+
+To verify that you set the remote URL correctly, run the following command.
+
+```bash
+git remote -v
+```
+
+Then, you can sync the content to upload it to your repository.
+
+```bash
+npx quartz sync
+```
--- a/docs/showcase.md
+++ b/docs/showcase.md
@ -6,9 +6,9 @@ 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/)
 - [Brandon Boswell's Garden](https://brandonkboswell.com)
 - [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/)
- [AWAGMI Intern Notes](https://notes.awagmi.xyz/)
 - [Data Dictionary 🧠](https://glossary.airbyte.com/)
 - [sspaeti.com's Second Brain](https://brain.sspaeti.com/)
 - [oldwinter の数字花园](https://garden.oldwinter.top/)
@ -20,5 +20,6 @@ Want to see what Quartz can do? Here are some cool community gardens:
 - [🧠🌳 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/)

 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)!
--- a/package-lock.json
+++ b/package-lock.json
@ -1,12 +1,12 @@
 {
  "name": "@jackyzha0/quartz",
-  "version": "4.1.0",
+  "version": "4.1.2",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@jackyzha0/quartz",
-      "version": "4.1.0",
+      "version": "4.1.2",
      "license": "MIT",
      "dependencies": {
        "@clack/prompts": "^0.6.3",
--- a/package.json
+++ b/package.json
@ -2,7 +2,7 @@
  "name": "@jackyzha0/quartz",
  "description": "🌱 publish your digital garden and notes as a website",
  "private": true,
-  "version": "4.1.0",
+  "version": "4.1.2",
  "type": "module",
  "author": "jackyzha0 <j.zhao2k19@gmail.com>",
  "license": "MIT",
--- a/quartz/cli/args.js
+++ b/quartz/cli/args.js
@ -41,6 +41,11 @@ export const SyncArgv = {
    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,
--- a/quartz/cli/handlers.js
+++ b/quartz/cli/handlers.js
@ -196,6 +196,11 @@ See the [documentation](https://quartz.jzhao.xyz) for how to get started.
  )
  await fs.promises.writeFile(configFilePath, configContent)

+  // setup remote
+  execSync(
+    `git remote show upstream || git remote add upstream https://github.com/jackyzha0/quartz.git`,
+  )
+
  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
@ -438,11 +443,23 @@ export async function handleUpdate(argv) {
  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)
+
+  try {
+    gitPull(UPSTREAM_NAME, QUARTZ_SOURCE_BRANCH)
+  } catch {
+    console.log(chalk.red("An error occured above while pulling updates."))
+    await popContentFolder(contentFolder)
+    return
+  }
+
  await popContentFolder(contentFolder)
  console.log("Ensuring dependencies are up to date")
-  spawnSync("npm", ["i"], { stdio: "inherit" })
-  console.log(chalk.green("Done!"))
+  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."))
+  }
 }

 /**
@ -483,8 +500,9 @@ export async function handleSync(argv) {
      dateStyle: "medium",
      timeStyle: "short",
    })
+    const commitMessage = argv.message ?? `Quartz sync: ${currentTimestamp}`
    spawnSync("git", ["add", "."], { stdio: "inherit" })
-    spawnSync("git", ["commit", "-m", `Quartz sync: ${currentTimestamp}`], { stdio: "inherit" })
+    spawnSync("git", ["commit", "-m", commitMessage], { stdio: "inherit" })

    if (contentStat.isSymbolicLink()) {
      // put symlink back
@ -498,13 +516,25 @@ export async function handleSync(argv) {
    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)
+    try {
+      gitPull(ORIGIN_NAME, QUARTZ_SOURCE_BRANCH)
+    } catch {
+      console.log(chalk.red("An error occured above while pulling updates."))
+      await popContentFolder(contentFolder)
+      return
+    }
  }

  await popContentFolder(contentFolder)
  if (argv.push) {
    console.log("Pushing your changes")
-    spawnSync("git", ["push", "-f", ORIGIN_NAME, QUARTZ_SOURCE_BRANCH], { stdio: "inherit" })
+    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!"))
--- a/quartz/cli/helpers.js
+++ b/quartz/cli/helpers.js
@ -36,7 +36,9 @@ 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(`Error while pulling updates: ${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"))
  }
 }

--- a/quartz/components/Breadcrumbs.tsx
+++ b/quartz/components/Breadcrumbs.tsx
@ -25,6 +25,10 @@ interface BreadcrumbOptions {
   * Wether to display breadcrumbs on root `index.md`
   */
  hideOnRoot: boolean
+  /**
+   * Wether to display the current page in the breadcrumbs.
+   */
+  showCurrentPage: boolean
 }

 const defaultOptions: BreadcrumbOptions = {
@ -32,6 +36,7 @@ const defaultOptions: BreadcrumbOptions = {
  rootName: "Home",
  resolveFrontmatterTitle: true,
  hideOnRoot: true,
+  showCurrentPage: true,
 }

 function formatCrumb(displayName: string, baseSlug: FullSlug, currentSlug: SimpleSlug): CrumbData {
@ -95,10 +100,12 @@ export default ((opts?: Partial<BreadcrumbOptions>) => {
      }

      // Add current file to crumb (can directly use frontmatter title)
-      crumbs.push({
-        displayName: fileData.frontmatter!.title,
-        path: "",
-      })
+      if (options.showCurrentPage) {
+        crumbs.push({
+          displayName: fileData.frontmatter!.title,
+          path: "",
+        })
+      }
    }
    return (
      <nav class={`breadcrumb-container ${displayClass ?? ""}`} aria-label="breadcrumbs">
--- a/quartz/components/pages/TagContent.tsx
+++ b/quartz/components/pages/TagContent.tsx
@ -27,7 +27,7 @@ function TagContent(props: QuartzComponentProps) {
      ? fileData.description
      : htmlToJsx(fileData.filePath!, tree)

-  if (tag === "") {
+  if (tag === "/") {
    const tags = [...new Set(allFiles.flatMap((data) => data.frontmatter?.tags ?? []))]
    const tagItemMap: Map<string, QuartzPluginData[]> = new Map()
    for (const tag of tags) {
--- a/quartz/components/renderPage.tsx
+++ b/quartz/components/renderPage.tsx
@ -3,9 +3,10 @@ import { QuartzComponent, QuartzComponentProps } from "./types"
 import HeaderConstructor from "./Header"
 import BodyConstructor from "./Body"
 import { JSResourceToScriptElement, StaticResources } from "../util/resources"
-import { FullSlug, RelativeURL, joinSegments } from "../util/path"
+import { FullSlug, RelativeURL, joinSegments, normalizeHastElement } from "../util/path"
 import { visit } from "unist-util-visit"
-import { Root, Element } from "hast"
+import { Root, Element, ElementContent } from "hast"
+import { QuartzPluginData } from "../plugins/vfile"

 interface RenderComponents {
  head: QuartzComponent
@ -49,6 +50,18 @@ export function pageResources(
  }
 }

+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,
@ -61,22 +74,83 @@ export function renderPage(
      const classNames = (node.properties?.className ?? []) as string[]
      if (classNames.includes("transclude")) {
        const inner = node.children[0] as Element
-        const blockSlug = inner.properties?.["data-slug"] as FullSlug
-        const blockRef = node.properties!.dataBlock as string
+        const transcludeTarget = inner.properties?.["data-slug"] as FullSlug
+        const page = getOrComputeFileIndex(componentData.allFiles).get(transcludeTarget)
+        if (!page) {
+          return
+        }

-        // TODO: avoid this expensive find operation and construct an index ahead of time
-        let blockNode = componentData.allFiles.find((f) => f.slug === blockSlug)?.blocks?.[blockRef]
-        if (blockNode) {
-          if (blockNode.tagName === "li") {
-            blockNode = {
-              type: "element",
-              tagName: "ul",
-              children: [blockNode],
+        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",
+                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 = [
-            blockNode,
+            ...(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",
+              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",
--- a/quartz/components/scripts/explorer.inline.ts
+++ b/quartz/components/scripts/explorer.inline.ts
@ -120,9 +120,9 @@ function setupExplorer() {
        }
      }
    })
-  } else {
+  } else if (explorer?.dataset.tree) {
    // If tree is not in localStorage or config is disabled, use tree passed from Explorer as dataset
-    explorerState = JSON.parse(explorer?.dataset.tree as string)
+    explorerState = JSON.parse(explorer.dataset.tree)
  }
 }

@ -130,12 +130,13 @@ window.addEventListener("resize", setupExplorer)
 document.addEventListener("nav", () => {
  setupExplorer()

-  const explorerContent = document.getElementById("explorer-ul")
+  observer.disconnect()
+
  // select pseudo element at end of list
  const lastItem = document.getElementById("explorer-end")
-
-  observer.disconnect()
-  observer.observe(lastItem as Element)
+  if (lastItem) {
+    observer.observe(lastItem)
+  }
 })

 /**
--- a/quartz/components/scripts/graph.inline.ts
+++ b/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"
@ -46,20 +46,22 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
    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[] = []
  const tags: SimpleSlug[] = []

-  const validLinks = new Set(Object.keys(data).map((slug) => simplifySlug(slug as FullSlug)))
-
-  for (const [src, details] of Object.entries<ContentDetails>(data)) {
-    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 (validLinks.has(dest)) {
-        links.push({ source, target: dest })
+        links.push({ source: source, target: dest })
      }
    }

@ -71,7 +73,7 @@ async function renderGraph(container: string, fullSlug: FullSlug) {
      tags.push(...localTags.filter((tag) => !tags.includes(tag)))

      for (const tag of localTags) {
-        links.push({ source, target: tag })
+        links.push({ source: source, target: tag })
      }
    }
  }
@ -93,17 +95,17 @@ 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) => {
-      const text = url.startsWith("tags/") ? "#" + url.substring(5) : data[url]?.title ?? url
+      const text = url.startsWith("tags/") ? "#" + url.substring(5) : data.get(url)?.title ?? url
      return {
        id: url,
        text: text,
-        tags: data[url]?.tags ?? [],
+        tags: data.get(url)?.tags ?? [],
      }
    }),
    links: links.filter((l) => neighbourhood.has(l.source) && neighbourhood.has(l.target)),
@ -200,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))
--- a/quartz/components/scripts/popover.inline.ts
+++ b/quartz/components/scripts/popover.inline.ts
@ -1,16 +1,5 @@
 import { computePosition, flip, inline, shift } from "@floating-ui/dom"
-
-// 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))
-}
+import { normalizeRelativeURLs } from "../../util/path"

 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()],
@ -43,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())
--- a/quartz/components/scripts/spa.inline.ts
+++ b/quartz/components/scripts/spa.inline.ts
@ -1,10 +1,8 @@
 import micromorph from "micromorph"
-import { FullSlug, RelativeURL, getFullSlug } from "../../util/path"
-import { normalizeRelativeURLs } from "./popover.inline"
+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 =>
@ -45,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)
    })
@ -109,6 +114,7 @@ function createRouter() {
      if (isSamePage(url) && url.hash) {
        const el = document.getElementById(decodeURIComponent(url.hash.substring(1)))
        el?.scrollIntoView()
+        history.pushState({}, "", url)
        return
      }

--- a/quartz/components/styles/toc.scss
+++ b/quartz/components/styles/toc.scss
@ -30,6 +30,7 @@ button#toc {
  overflow: hidden;
  max-height: none;
  transition: max-height 0.5s ease;
+  position: relative;

  &.collapsed > .overflow::after {
    opacity: 0;
--- a/quartz/plugins/emitters/cname.ts
+++ b/quartz/plugins/emitters/cname.ts
@ -0,0 +1,29 @@
+import { FilePath, joinSegments } from "../../util/path"
+import { QuartzEmitterPlugin } from "../types"
+import fs from "fs"
+import chalk from "chalk"
+
+export function extractDomainFromBaseUrl(baseUrl: string) {
+  const url = new URL(`https://${baseUrl}`)
+  return url.hostname
+}
+
+export const CNAME: QuartzEmitterPlugin = () => ({
+  name: "CNAME",
+  getQuartzComponents() {
+    return []
+  },
+  async emit({ argv, cfg }, _content, _resources, _emit): Promise<FilePath[]> {
+    if (!cfg.configuration.baseUrl) {
+      console.warn(chalk.yellow("CNAME emitter requires `baseUrl` to be set in your configuration"))
+      return []
+    }
+    const path = joinSegments(argv.output, "CNAME")
+    const content = extractDomainFromBaseUrl(cfg.configuration.baseUrl)
+    if (!content) {
+      return []
+    }
+    fs.writeFileSync(path, content)
+    return [path] as FilePath[]
+  },
+})
--- a/quartz/plugins/emitters/index.ts
+++ b/quartz/plugins/emitters/index.ts
@ -7,3 +7,4 @@ export { Assets } from "./assets"
 export { Static } from "./static"
 export { ComponentResources } from "./componentResources"
 export { NotFoundPage } from "./404"
+export { CNAME } from "./cname"
--- a/quartz/plugins/emitters/static.ts
+++ b/quartz/plugins/emitters/static.ts
@ -11,7 +11,10 @@ export const Static: QuartzEmitterPlugin = () => ({
  async emit({ argv, cfg }, _content, _resources, _emit): Promise<FilePath[]> {
    const staticPath = joinSegments(QUARTZ, "static")
    const fps = await glob("**", staticPath, cfg.configuration.ignorePatterns)
-    await fs.promises.cp(staticPath, joinSegments(argv.output, "static"), { recursive: true })
+    await fs.promises.cp(staticPath, joinSegments(argv.output, "static"), {
+      recursive: true,
+      dereference: true,
+    })
    return fps.map((fp) => joinSegments(argv.output, "static", fp)) as FilePath[]
  },
 })
--- a/quartz/plugins/emitters/tagPage.tsx
+++ b/quartz/plugins/emitters/tagPage.tsx
@ -45,7 +45,7 @@ export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (userOpts) => {

      const tagDescriptions: Record<string, ProcessedContent> = Object.fromEntries(
        [...tags].map((tag) => {
-          const title = tag === "" ? "Tag Index" : `Tag: #${tag}`
+          const title = tag === "index" ? "Tag Index" : `Tag: #${tag}`
          return [
            tag,
            defaultProcessedContent({
--- a/quartz/plugins/transformers/frontmatter.ts
+++ b/quartz/plugins/transformers/frontmatter.ts
@ -4,15 +4,18 @@ import { QuartzTransformerPlugin } from "../types"
 import yaml from "js-yaml"
 import toml from "toml"
 import { slugTag } from "../../util/path"
+import { QuartzPluginData } from "../vfile"

 export interface Options {
  delims: string | string[]
  language: "yaml" | "toml"
+  oneLineTagDelim: string
 }

 const defaultOptions: Options = {
  delims: "---",
  language: "yaml",
+  oneLineTagDelim: ",",
 }

 export const FrontMatter: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
@ -20,6 +23,8 @@ export const FrontMatter: QuartzTransformerPlugin<Partial<Options> | undefined>
  return {
    name: "FrontMatter",
    markdownPlugins() {
+      const { oneLineTagDelim } = opts
+
      return [
        [remarkFrontmatter, ["yaml", "toml"]],
        () => {
@ -40,12 +45,14 @@ export const FrontMatter: QuartzTransformerPlugin<Partial<Options> | undefined>
            // coerce title to string
            if (data.title) {
              data.title = data.title.toString()
+            } else if (data.title === null || data.title === undefined) {
+              data.title = file.stem ?? "Untitled"
            }

            if (data.tags && !Array.isArray(data.tags)) {
              data.tags = data.tags
                .toString()
-                .split(",")
+                .split(oneLineTagDelim)
                .map((tag: string) => tag.trim())
            }

@ -53,11 +60,7 @@ export const FrontMatter: QuartzTransformerPlugin<Partial<Options> | undefined>
            data.tags = [...new Set(data.tags?.map((tag: string) => slugTag(tag)))] ?? []

            // fill in frontmatter
-            file.data.frontmatter = {
-              title: file.stem ?? "Untitled",
-              tags: [],
-              ...data,
-            }
+            file.data.frontmatter = data as QuartzPluginData["frontmatter"]
          }
        },
      ]
--- a/quartz/plugins/transformers/gfm.ts
+++ b/quartz/plugins/transformers/gfm.ts
@ -31,6 +31,11 @@ export const GitHubFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options> |
            rehypeAutolinkHeadings,
            {
              behavior: "append",
+              properties: {
+                ariaHidden: true,
+                tabIndex: -1,
+                "data-no-popover": true,
+              },
              content: {
                type: "text",
                value: " §",
--- a/quartz/plugins/transformers/links.ts
+++ b/quartz/plugins/transformers/links.ts
@ -54,6 +54,16 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
                node.properties.className ??= []
                node.properties.className.push(isAbsoluteUrl(dest) ? "external" : "internal")

+                // Check if the link has alias text
+                if (
+                  node.children.length === 1 &&
+                  node.children[0].type === "text" &&
+                  node.children[0].value !== dest
+                ) {
+                  // Add the 'alias' class if the text content is not the same as the href
+                  node.properties.className.push("alias")
+                }
+
                if (opts.openLinksInNewTab) {
                  node.properties.target = "_blank"
                }
@ -71,14 +81,16 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
                  // WHATWG equivalent https://nodejs.dev/en/api/v18/url/#urlresolvefrom-to
                  const url = new URL(dest, `https://base.com/${curSlug}`)
                  const canonicalDest = url.pathname
-                  const [destCanonical, _destAnchor] = splitAnchor(canonicalDest)
+                  let [destCanonical, _destAnchor] = splitAnchor(canonicalDest)
+                  if (destCanonical.endsWith("/")) {
+                    destCanonical += "index"
+                  }

                  // need to decodeURIComponent here as WHATWG URL percent-encodes everything
-                  const simple = decodeURIComponent(
-                    simplifySlug(destCanonical as FullSlug),
-                  ) as SimpleSlug
+                  const full = decodeURIComponent(_stripSlashes(destCanonical, true)) as FullSlug
+                  const simple = simplifySlug(full)
                  outgoing.add(simple)
-                  node.properties["data-slug"] = simple
+                  node.properties["data-slug"] = full
                }

                // rewrite link internals if prettylinks is on
--- a/quartz/plugins/transformers/ofm.ts
+++ b/quartz/plugins/transformers/ofm.ts
@ -1,7 +1,7 @@
 import { PluggableList } from "unified"
 import { QuartzTransformerPlugin } from "../types"
 import { Root, HTML, BlockContent, DefinitionContent, Code, Paragraph } from "mdast"
-import { Element, Literal } from "hast"
+import { Element, Literal, Root as HtmlRoot } from "hast"
 import { Replace, findAndReplace as mdastFindReplace } from "mdast-util-find-and-replace"
 import { slug as slugAnchor } from "github-slugger"
 import rehypeRaw from "rehype-raw"
@ -110,7 +110,10 @@ function canonicalizeCallout(calloutName: string): keyof typeof callouts {
 // ([^\[\]\|\#]+)   -> one or more non-special characters ([,],|, or #) (name)
 // (#[^\[\]\|\#]+)? -> # then one or more non-special characters (heading link)
 // (|[^\[\]\|\#]+)? -> | then one or more non-special characters (alias)
-const wikilinkRegex = new RegExp(/!?\[\[([^\[\]\|\#]+)?(#[^\[\]\|\#]+)?(\|[^\[\]\|\#]+)?\]\]/, "g")
+export const wikilinkRegex = new RegExp(
+  /!?\[\[([^\[\]\|\#]+)?(#+[^\[\]\|\#]+)?(\|[^\[\]\|\#]+)?\]\]/,
+  "g",
+)
 const highlightRegex = new RegExp(/==([^=]+)==/, "g")
 const commentRegex = new RegExp(/%%(.+)%%/, "g")
 // from https://github.com/escwxyz/remark-obsidian-callout/blob/main/src/index.ts
@ -178,8 +181,9 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
        src = src.replaceAll(wikilinkRegex, (value, ...capture) => {
          const [rawFp, rawHeader, rawAlias] = capture
          const fp = rawFp ?? ""
-          const anchor = rawHeader?.trim().slice(1)
-          const displayAnchor = anchor ? `#${slugAnchor(anchor)}` : ""
+          const anchor = rawHeader?.trim().replace(/^#+/, "")
+          const blockRef = Boolean(anchor?.startsWith("^")) ? "^" : ""
+          const displayAnchor = anchor ? `#${blockRef}${slugAnchor(anchor)}` : ""
          const displayAlias = rawAlias ?? rawHeader?.replace("#", "|") ?? ""
          const embedDisplay = value.startsWith("!") ? "!" : ""
          return `${embedDisplay}[[${fp}${displayAnchor}${displayAlias}]]`
@ -236,13 +240,13 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
                    value: `<iframe src="${url}"></iframe>`,
                  }
                } else if (ext === "") {
-                  const block = anchor.slice(1)
+                  const block = anchor
                  return {
                    type: "html",
                    data: { hProperties: { transclude: true } },
                    value: `<blockquote class="transclude" data-url="${url}" data-block="${block}"><a href="${
                      url + anchor
-                    }" class="transclude-inner">Transclude of block ${block}</a></blockquote>`,
+                    }" class="transclude-inner">Transclude of ${url}${block}</a></blockquote>`,
                  }
                }

@ -477,6 +481,8 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
                }
              }
            })
+
+            file.data.htmlAst = tree
          }
        })
      }
@ -524,5 +530,6 @@ export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>
 declare module "vfile" {
  interface DataMap {
    blocks: Record<string, Element>
+    htmlAst: HtmlRoot
  }
 }
--- a/quartz/plugins/transformers/toc.ts
+++ b/quartz/plugins/transformers/toc.ts
@ -3,6 +3,7 @@ import { Root } from "mdast"
 import { visit } from "unist-util-visit"
 import { toString } from "mdast-util-to-string"
 import Slugger from "github-slugger"
+import { wikilinkRegex } from "./ofm"

 export interface Options {
  maxDepth: 1 | 2 | 3 | 4 | 5 | 6
@ -24,6 +25,7 @@ interface TocEntry {
  slug: string // this is just the anchor (#some-slug), not the canonical slug
 }

+const regexMdLinks = new RegExp(/\[([^\[]+)\](\(.*\))/, "g")
 export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefined> = (
  userOpts,
 ) => {
@ -41,7 +43,16 @@ export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefin
              let highestDepth: number = opts.maxDepth
              visit(tree, "heading", (node) => {
                if (node.depth <= opts.maxDepth) {
-                  const text = toString(node)
+                  let text = toString(node)
+
+                  // strip link formatting from toc entries
+                  text = text.replace(wikilinkRegex, (_, rawFp, __, rawAlias) => {
+                    const fp = rawFp?.trim() ?? ""
+                    const alias = rawAlias?.slice(1).trim()
+                    return alias ?? fp
+                  })
+                  text = text.replace(regexMdLinks, "$1")
+
                  highestDepth = Math.min(highestDepth, node.depth)
                  toc.push({
                    depth: node.depth,
--- a/quartz/styles/base.scss
+++ b/quartz/styles/base.scss
@ -64,11 +64,17 @@ a {
    color: var(--tertiary) !important;
  }

-  &.internal:not(:has(img)) {
+  &.internal {
    text-decoration: none;
    background-color: var(--highlight);
    padding: 0 0.1rem;
    border-radius: 5px;
+
+    &:has(> img) {
+      background-color: none;
+      border-radius: 0;
+      padding: 0;
+    }
  }
 }

@ -94,8 +100,6 @@ a {
  }

  & article {
-    position: relative;
-
    & > h1 {
      font-size: 2rem;
    }
--- a/quartz/util/path.test.ts
+++ b/quartz/util/path.test.ts
@ -83,7 +83,7 @@ describe("transforms", () => {
  test("simplifySlug", () => {
    asserts(
      [
-        ["index", ""],
+        ["index", "/"],
        ["abc", "abc"],
        ["abc/index", "abc/"],
        ["abc/def", "abc/def"],
--- a/quartz/util/path.ts
+++ b/quartz/util/path.ts
@ -1,4 +1,5 @@
 import { slug } from "github-slugger"
+import type { Element as HastElement } from "hast"
 // this file must be isomorphic so it can't use node libs (e.g. path)

 export const QUARTZ = "quartz"
@ -24,7 +25,7 @@ export function isFullSlug(s: string): s is FullSlug {
 /** Shouldn't be a relative path and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path. */
 export type SimpleSlug = SlugLike<"simple">
 export function isSimpleSlug(s: string): s is SimpleSlug {
-  const validStart = !(s.startsWith(".") || s.startsWith("/"))
+  const validStart = !(s.startsWith(".") || (s.length > 1 && s.startsWith("/")))
  const validEnding = !(s.endsWith("/index") || s === "index")
  return validStart && !_containsForbiddenCharacters(s) && validEnding && !_hasFileExtension(s)
 }
@ -65,7 +66,8 @@ export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug {
 }

 export function simplifySlug(fp: FullSlug): SimpleSlug {
-  return _stripSlashes(_trimSuffix(fp, "index"), true) as SimpleSlug
+  const res = _stripSlashes(_trimSuffix(fp, "index"), true)
+  return (res.length === 0 ? "/" : res) as SimpleSlug
 }

 export function transformInternalLink(link: string): RelativeURL {
@ -84,6 +86,49 @@ export function transformInternalLink(link: string): RelativeURL {
  return res
 }

+// from micromorph/src/utils.ts
+// https://github.com/natemoo-re/micromorph/blob/main/src/utils.ts#L5
+const _rebaseHtmlElement = (el: Element, attr: string, newBase: string | URL) => {
+  const rebased = new URL(el.getAttribute(attr)!, newBase)
+  el.setAttribute(attr, rebased.pathname + rebased.hash)
+}
+export function normalizeRelativeURLs(el: Element | Document, destination: string | URL) {
+  el.querySelectorAll('[href^="./"], [href^="../"]').forEach((item) =>
+    _rebaseHtmlElement(item, "href", destination),
+  )
+  el.querySelectorAll('[src^="./"], [src^="../"]').forEach((item) =>
+    _rebaseHtmlElement(item, "src", destination),
+  )
+}
+
+const _rebaseHastElement = (
+  el: HastElement,
+  attr: string,
+  curBase: FullSlug,
+  newBase: FullSlug,
+) => {
+  if (el.properties?.[attr]) {
+    if (!isRelativeURL(String(el.properties[attr]))) {
+      return
+    }
+
+    const rel = joinSegments(resolveRelative(curBase, newBase), "..", el.properties[attr] as string)
+    el.properties[attr] = rel
+  }
+}
+
+export function normalizeHastElement(el: HastElement, curBase: FullSlug, newBase: FullSlug) {
+  _rebaseHastElement(el, "src", curBase, newBase)
+  _rebaseHastElement(el, "href", curBase, newBase)
+  if (el.children) {
+    el.children = el.children.map((child) =>
+      normalizeHastElement(child as HastElement, curBase, newBase),
+    )
+  }
+
+  return el
+}
+
 // resolve /a/b/c to ../..
 export function pathToRoot(slug: FullSlug): RelativeURL {
  let rootPath = slug