Merge remote-tracking branch 'upstream/v4' into open-graph

docs/hosting.md

@@ -61,6 +61,8 @@ jobs:
         with:
           fetch-depth: 0 # Fetch all history for git info
       - uses: actions/setup-node@v4
+        with:
+          node-version: 22
       - name: Install Dependencies
         run: npm ci
       - name: Build Quartz

docs/plugins/Latex.md

@@ -12,6 +12,7 @@ This plugin adds LaTeX support to Quartz. See [[features/Latex|Latex]] for more
 This plugin accepts the following configuration options:
 
 - `renderEngine`: the engine to use to render LaTeX equations. Can be `"katex"` for [KaTeX](https://katex.org/) or `"mathjax"` for [MathJax](https://www.mathjax.org/) [SVG rendering](https://docs.mathjax.org/en/latest/output/svg.html). Defaults to KaTeX.
+- `customMacros`: custom macros for all LaTeX blocks. It takes the form of a key-value pair where the key is a new command name and the value is the expansion of the macro. For example: `{"\\R": "\\mathbb{R}"}`
 
 ## API
 

docs/showcase.md

@@ -25,5 +25,7 @@ Want to see what Quartz can do? Here are some cool community gardens:
 - [🪴Aster's notebook](https://notes.asterhu.com)
 - [Gatekeeper Wiki](https://www.gatekeeper.wiki)
 - [Ellie's Notes](https://ellie.wtf)
+- [🥷🏻🌳🍃 Computer Science & Thinkering Garden](https://notes.yxy.ninja)
+- [Eledah's Crystalline](https://blog.eledah.ir/)
 
 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)!

package.json

@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@floating-ui/dom": "^1.6.8",
-    "@napi-rs/simple-git": "0.1.16",
+    "@floating-ui/dom": "^1.6.10",
+    "@napi-rs/simple-git": "0.1.17",
     "async-mutex": "^0.5.0",
     "chalk": "^5.3.0",
     "chokidar": "^3.6.0",
@@ -53,19 +53,19 @@
     "hast-util-to-string": "^3.0.0",
     "is-absolute-url": "^4.0.1",
     "js-yaml": "^4.1.0",
-    "lightningcss": "^1.25.1",
+    "lightningcss": "^1.26.0",
     "mdast-util-find-and-replace": "^3.0.1",
     "mdast-util-to-hast": "^13.2.0",
     "mdast-util-to-string": "^4.0.0",
     "micromorph": "^0.4.5",
-    "preact": "^10.22.1",
-    "preact-render-to-string": "^6.5.7",
+    "preact": "^10.23.2",
+    "preact-render-to-string": "^6.5.9",
     "pretty-bytes": "^6.1.1",
     "pretty-time": "^1.1.0",
     "reading-time": "^1.5.0",
     "rehype-autolink-headings": "^7.1.0",
-    "rehype-citation": "^2.0.0",
-    "rehype-katex": "^7.0.0",
+    "rehype-citation": "^2.1.1",
+    "rehype-katex": "^7.0.1",
     "rehype-mathjax": "^6.0.0",
     "rehype-pretty-code": "^0.13.2",
     "rehype-raw": "^7.0.0",
@@ -83,7 +83,7 @@
     "satori": "^0.10.6",
     "serve-handler": "^6.1.5",
     "sharp": "^0.32.6",
-    "shiki": "^1.10.3",
+    "shiki": "^1.12.1",
     "source-map-support": "^0.5.21",
     "to-vfile": "^8.0.0",
     "toml": "^3.0.0",
@@ -106,7 +106,7 @@
     "@types/yargs": "^17.0.32",
     "esbuild": "^0.19.9",
     "prettier": "^3.3.3",
-    "tsx": "^4.16.2",
-    "typescript": "^5.5.3"
+    "tsx": "^4.17.0",
+    "typescript": "^5.5.4"
   }
 }

quartz/build.ts

@@ -38,8 +38,13 @@ type BuildData = {
 
 type FileEvent = "add" | "change" | "delete"
 
+function newBuildId() {
+  return new Date().toISOString()
+}
+
 async function buildQuartz(argv: Argv, mut: Mutex, clientRefresh: () => void) {
   const ctx: BuildCtx = {
+    buildId: newBuildId(),
     argv,
     cfg,
     allSlugs: [],
@@ -167,6 +172,7 @@ async function partialRebuildFromEntrypoint(
 
   const perf = new PerfTimer()
   console.log(chalk.yellow("Detected change, rebuilding..."))
+  ctx.buildId = newBuildId()
 
   // UPDATE DEP GRAPH
   const fp = joinSegments(argv.directory, toPosixPath(filepath)) as FilePath
@@ -363,14 +369,10 @@ async function rebuildFromEntrypoint(
 
   const perf = new PerfTimer()
   console.log(chalk.yellow("Detected change, rebuilding..."))
+  ctx.buildId = newBuildId()
+
   try {
     const filesToRebuild = [...toRebuild].filter((fp) => !toRemove.has(fp))
-
-    const trackedSlugs = [...new Set([...contentMap.keys(), ...toRebuild, ...trackedAssets])]
-      .filter((fp) => !toRemove.has(fp))
-      .map((fp) => slugifyFilePath(path.posix.relative(argv.directory, fp) as FilePath))
-
-    ctx.allSlugs = [...new Set([...initialSlugs, ...trackedSlugs])]
     const parsedContent = await parseMarkdown(ctx, filesToRebuild)
     for (const content of parsedContent) {
       const [_tree, vfile] = content
@@ -384,6 +386,13 @@ async function rebuildFromEntrypoint(
     const parsedFiles = [...contentMap.values()]
     const filteredContent = filterContent(ctx, parsedFiles)
 
+    // re-update slugs
+    const trackedSlugs = [...new Set([...contentMap.keys(), ...toRebuild, ...trackedAssets])]
+      .filter((fp) => !toRemove.has(fp))
+      .map((fp) => slugifyFilePath(path.posix.relative(argv.directory, fp) as FilePath))
+
+    ctx.allSlugs = [...new Set([...initialSlugs, ...trackedSlugs])]
+
     // TODO: we can probably traverse the link graph to figure out what's safe to delete here
     // instead of just deleting everything
     await rimraf(path.join(argv.output, ".*"), { glob: true })

quartz/components/Explorer.tsx

@@ -44,12 +44,9 @@ export default ((userOpts?: Partial<Options>) => {
   // memoized
   let fileTree: FileNode
   let jsonTree: string
+  let lastBuildId: string = ""
 
   function constructFileTree(allFiles: QuartzPluginData[]) {
-    if (fileTree) {
-      return
-    }
-
     // Construct tree from allFiles
     fileTree = new FileNode("")
     allFiles.forEach((file) => fileTree.add(file))
@@ -76,12 +73,17 @@ export default ((userOpts?: Partial<Options>) => {
   }
 
   const Explorer: QuartzComponent = ({
+    ctx,
     cfg,
     allFiles,
     displayClass,
     fileData,
   }: QuartzComponentProps) => {
-    constructFileTree(allFiles)
+    if (ctx.buildId !== lastBuildId) {
+      lastBuildId = ctx.buildId
+      constructFileTree(allFiles)
+    }
+
     return (
       <div class={classNames(displayClass, "explorer")}>
         <button
@@ -91,6 +93,8 @@ export default ((userOpts?: Partial<Options>) => {
           data-collapsed={opts.folderDefaultState}
           data-savestate={opts.useSavedState}
           data-tree={jsonTree}
+          aria-controls="explorer-content"
+          aria-expanded={opts.folderDefaultState === "open"}
         >
           <h2>{opts.title ?? i18n(cfg.locale).components.explorer.title}</h2>
           <svg

quartz/components/Search.tsx

@@ -19,24 +19,16 @@ export default ((userOpts?: Partial<SearchOptions>) => {
     const searchPlaceholder = i18n(cfg.locale).components.search.searchBarPlaceholder
     return (
       <div class={classNames(displayClass, "search")}>
-        <div id="search-icon">
+        <button class="search-button" id="search-button">
           <p>{i18n(cfg.locale).components.search.title}</p>
-          <div></div>
-          <svg
-            tabIndex={0}
-            aria-labelledby="title desc"
-            role="img"
-            xmlns="http://www.w3.org/2000/svg"
-            viewBox="0 0 19.9 19.7"
-          >
-            <title id="title">Search</title>
-            <desc id="desc">Search</desc>
+          <svg role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.9 19.7">
+            <title>Search</title>
             <g class="search-path" fill="none">
               <path stroke-linecap="square" d="M18.5 18.3l-5.4-5.4" />
               <circle cx="8" cy="8" r="7" />
             </g>
           </svg>
-        </div>
+        </button>
         <div id="search-container">
           <div id="search-space">
             <input

quartz/components/TableOfContents.tsx

@@ -26,7 +26,13 @@ const TableOfContents: QuartzComponent = ({
 
   return (
     <div class={classNames(displayClass, "toc")}>
-      <button type="button" id="toc" class={fileData.collapseToc ? "collapsed" : ""}>
+      <button
+        type="button"
+        id="toc"
+        class={fileData.collapseToc ? "collapsed" : ""}
+        aria-controls="toc-content"
+        aria-expanded={!fileData.collapseToc}
+      >
         <h3>{i18n(cfg.locale).components.tableOfContents.title}</h3>
         <svg
           xmlns="http://www.w3.org/2000/svg"

quartz/components/scripts/explorer.inline.ts

@@ -17,6 +17,10 @@ const observer = new IntersectionObserver((entries) => {
 
 function toggleExplorer(this: HTMLElement) {
   this.classList.toggle("collapsed")
+  this.setAttribute(
+    "aria-expanded",
+    this.getAttribute("aria-expanded") === "true" ? "false" : "true",
+  )
   const content = this.nextElementSibling as MaybeHTMLElement
   if (!content) return
 

quartz/components/scripts/search.inline.ts

@@ -148,7 +148,7 @@ document.addEventListener("nav", async (e: CustomEventMap["nav"]) => {
   const data = await fetchData
   const container = document.getElementById("search-container")
   const sidebar = container?.closest(".sidebar") as HTMLElement
-  const searchIcon = document.getElementById("search-icon")
+  const searchButton = document.getElementById("search-button")
   const searchBar = document.getElementById("search-bar") as HTMLInputElement | null
   const searchLayout = document.getElementById("search-layout")
   const idDataMap = Object.keys(data) as FullSlug[]
@@ -191,6 +191,8 @@ document.addEventListener("nav", async (e: CustomEventMap["nav"]) => {
     }
 
     searchType = "basic" // reset search type after closing
+
+    searchButton?.focus()
   }
 
   function showSearch(searchTypeNew: SearchType) {
@@ -458,8 +460,8 @@ document.addEventListener("nav", async (e: CustomEventMap["nav"]) => {
 
   document.addEventListener("keydown", shortcutHandler)
   window.addCleanup(() => document.removeEventListener("keydown", shortcutHandler))
-  searchIcon?.addEventListener("click", () => showSearch("basic"))
-  window.addCleanup(() => searchIcon?.removeEventListener("click", () => showSearch("basic")))
+  searchButton?.addEventListener("click", () => showSearch("basic"))
+  window.addCleanup(() => searchButton?.removeEventListener("click", () => showSearch("basic")))
   searchBar?.addEventListener("input", onType)
   window.addCleanup(() => searchBar?.removeEventListener("input", onType))
 

quartz/components/scripts/toc.inline.ts

@@ -16,6 +16,10 @@ const observer = new IntersectionObserver((entries) => {
 
 function toggleToc(this: HTMLElement) {
   this.classList.toggle("collapsed")
+  this.setAttribute(
+    "aria-expanded",
+    this.getAttribute("aria-expanded") === "true" ? "false" : "true",
+  )
   const content = this.nextElementSibling as HTMLElement | undefined
   if (!content) return
   content.classList.toggle("collapsed")

quartz/components/scripts/util.ts

@@ -3,6 +3,7 @@ export function registerEscapeHandler(outsideContainer: HTMLElement | null, cb:
   function click(this: HTMLElement, e: HTMLElementEventMap["click"]) {
     if (e.target !== this) return
     e.preventDefault()
+    e.stopPropagation()
     cb()
   }
 

quartz/components/styles/explorer.scss

@@ -1,7 +1,6 @@
 @use "../../styles/variables.scss" as *;
 
 button#explorer {
-  all: unset;
   background-color: transparent;
   border: none;
   text-align: left;
@@ -46,8 +45,18 @@ button#explorer {
   list-style: none;
   overflow: hidden;
   max-height: none;
-  transition: max-height 0.35s ease;
+  transition:
+    max-height 0.35s ease,
+    visibility 0s linear 0s;
   margin-top: 0.5rem;
+  visibility: visible;
+
+  &.collapsed {
+    transition:
+      max-height 0.35s ease,
+      visibility 0s linear 0.35s;
+    visibility: hidden;
+  }
 
   &.collapsed > .overflow::after {
     opacity: 0;

quartz/components/styles/search.scss

@@ -5,18 +5,21 @@
   max-width: 14rem;
   flex-grow: 0.3;
 
-  & > #search-icon {
+  & > .search-button {
     background-color: var(--lightgray);
+    border: none;
     border-radius: 4px;
+    font-family: inherit;
+    font-size: inherit;
     height: 2rem;
+    padding: 0;
     display: flex;
     align-items: center;
+    text-align: inherit;
     cursor: pointer;
     white-space: nowrap;
-
-    & > div {
-      flex-grow: 1;
-    }
+    width: 100%;
+    justify-content: space-between;
 
     & > p {
       display: inline;

quartz/components/styles/toc.scss

@@ -29,8 +29,18 @@ button#toc {
   list-style: none;
   overflow: hidden;
   max-height: none;
-  transition: max-height 0.5s ease;
+  transition:
+    max-height 0.5s ease,
+    visibility 0s linear 0s;
   position: relative;
+  visibility: visible;
+
+  &.collapsed {
+    transition:
+      max-height 0.5s ease,
+      visibility 0s linear 0.5s;
+    visibility: hidden;
+  }
 
   &.collapsed > .overflow::after {
     opacity: 0;

quartz/plugins/transformers/citations.ts

@@ -17,7 +17,7 @@ const defaultOptions: Options = {
   csl: "apa",
 }
 
-export const Citations: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
+export const Citations: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "Citations",
@@ -38,7 +38,7 @@ export const Citations: QuartzTransformerPlugin<Partial<Options> | undefined> =
       // using https://github.com/syntax-tree/unist-util-visit as they're just anochor links
       plugins.push(() => {
         return (tree, _file) => {
-          visit(tree, "element", (node, index, parent) => {
+          visit(tree, "element", (node, _index, _parent) => {
             if (node.tagName === "a" && node.properties?.href?.startsWith("#bib")) {
               node.properties["data-no-popover"] = true
             }

quartz/plugins/transformers/description.ts

@@ -18,7 +18,7 @@ const urlRegex = new RegExp(
   "g",
 )
 
-export const Description: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
+export const Description: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "Description",

quartz/plugins/transformers/frontmatter.ts

@@ -40,7 +40,7 @@ function coerceToArray(input: string | string[]): string[] | undefined {
     .map((tag: string | number) => tag.toString())
 }
 
-export const FrontMatter: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
+export const FrontMatter: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "FrontMatter",

quartz/plugins/transformers/gfm.ts

@@ -14,9 +14,7 @@ const defaultOptions: Options = {
   linkHeadings: true,
 }
 
-export const GitHubFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options> | undefined> = (
-  userOpts,
-) => {
+export const GitHubFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "GitHubFlavoredMarkdown",

quartz/plugins/transformers/lastmod.ts

@@ -27,9 +27,7 @@ function coerceDate(fp: string, d: any): Date {
 }
 
 type MaybeDate = undefined | string | number
-export const CreatedModifiedDate: QuartzTransformerPlugin<Partial<Options> | undefined> = (
-  userOpts,
-) => {
+export const CreatedModifiedDate: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "CreatedModifiedDate",

quartz/plugins/transformers/latex.ts

@@ -5,10 +5,16 @@ import { QuartzTransformerPlugin } from "../types"
 
 interface Options {
   renderEngine: "katex" | "mathjax"
+  customMacros: MacroType
 }
 
-export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
+interface MacroType {
+  [key: string]: string
+}
+
+export const Latex: QuartzTransformerPlugin<Partial<Options>> = (opts) => {
   const engine = opts?.renderEngine ?? "katex"
+  const macros = opts?.customMacros ?? {}
   return {
     name: "Latex",
     markdownPlugins() {
@@ -16,9 +22,9 @@ export const Latex: QuartzTransformerPlugin<Options> = (opts?: Options) => {
     },
     htmlPlugins() {
       if (engine === "katex") {
-        return [[rehypeKatex, { output: "html" }]]
+        return [[rehypeKatex, { output: "html", macros }]]
       } else {
-        return [rehypeMathjax]
+        return [[rehypeMathjax, { macros }]]
       }
     },
     externalResources() {

quartz/plugins/transformers/links.ts

@@ -8,7 +8,6 @@ import {
   simplifySlug,
   splitAnchor,
   transformLink,
-  joinSegments,
 } from "../../util/path"
 import path from "path"
 import { visit } from "unist-util-visit"
@@ -33,7 +32,7 @@ const defaultOptions: Options = {
   externalLinkIcon: true,
 }
 
-export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
+export const CrawlLinks: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "LinkProcessing",
@@ -66,6 +65,7 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
                     type: "element",
                     tagName: "svg",
                     properties: {
+                      "aria-hidden": "true",
                       class: "external-icon",
                       viewBox: "0 0 512 512",
                     },

quartz/plugins/transformers/ofm.ts

@@ -136,9 +136,7 @@ const wikilinkImageEmbedRegex = new RegExp(
   /^(?<alt>(?!^\d*x?\d*$).*?)?(\|?\s*?(?<width>\d+)(x(?<height>\d+))?)?$/,
 )
 
-export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options> | undefined> = (
-  userOpts,
-) => {
+export const ObsidianFlavoredMarkdown: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
 
   const mdastToHtml = (ast: PhrasingContent | Paragraph) => {

quartz/plugins/transformers/oxhugofm.ts

@@ -47,9 +47,7 @@ const quartzLatexRegex = new RegExp(/\$\$[\s\S]*?\$\$|\$.*?\$/, "g")
  * markdown to make it compatible with quartz but the list of changes applied it
  * is not exhaustive.
  * */
-export const OxHugoFlavouredMarkdown: QuartzTransformerPlugin<Partial<Options> | undefined> = (
-  userOpts,
-) => {
+export const OxHugoFlavouredMarkdown: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "OxHugoFlavouredMarkdown",

quartz/plugins/transformers/syntax.ts

@@ -19,10 +19,8 @@ const defaultOptions: Options = {
   keepBackground: false,
 }
 
-export const SyntaxHighlighting: QuartzTransformerPlugin<Options> = (
-  userOpts?: Partial<Options>,
-) => {
-  const opts: Partial<CodeOptions> = { ...defaultOptions, ...userOpts }
+export const SyntaxHighlighting: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
+  const opts: CodeOptions = { ...defaultOptions, ...userOpts }
 
   return {
     name: "SyntaxHighlighting",

quartz/plugins/transformers/toc.ts

@@ -25,9 +25,7 @@ interface TocEntry {
 }
 
 const slugAnchor = new Slugger()
-export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefined> = (
-  userOpts,
-) => {
+export const TableOfContents: QuartzTransformerPlugin<Partial<Options>> = (userOpts) => {
   const opts = { ...defaultOptions, ...userOpts }
   return {
     name: "TableOfContents",

quartz/processors/parse.ts

@@ -143,7 +143,7 @@ export async function parseMarkdown(ctx: BuildCtx, fps: FilePath[]): Promise<Pro
 
     const childPromises: WorkerPromise<ProcessedContent[]>[] = []
     for (const chunk of chunks(fps, CHUNK_SIZE)) {
-      childPromises.push(pool.exec("parseFiles", [argv, chunk, ctx.allSlugs]))
+      childPromises.push(pool.exec("parseFiles", [ctx.buildId, argv, chunk, ctx.allSlugs]))
     }
 
     const results: ProcessedContent[][] = await WorkerPromise.all(childPromises).catch((err) => {

quartz/util/ctx.ts

@@ -14,6 +14,7 @@ export interface Argv {
 }
 
 export interface BuildCtx {
+  buildId: string
   argv: Argv
   cfg: QuartzConfig
   allSlugs: FullSlug[]

quartz/worker.ts

@@ -7,8 +7,14 @@ import { createFileParser, createProcessor } from "./processors/parse"
 import { options } from "./util/sourcemap"
 
 // only called from worker thread
-export async function parseFiles(argv: Argv, fps: FilePath[], allSlugs: FullSlug[]) {
+export async function parseFiles(
+  buildId: string,
+  argv: Argv,
+  fps: FilePath[],
+  allSlugs: FullSlug[],
+) {
   const ctx: BuildCtx = {
+    buildId,
     cfg,
     argv,
     allSlugs,