Initial commit

quartz/util/ctx.ts

@@ -0,0 +1,21 @@
+import { QuartzConfig } from "../cfg"
+import { FullSlug } from "./path"
+
+export interface Argv {
+  directory: string
+  verbose: boolean
+  output: string
+  serve: boolean
+  fastRebuild: boolean
+  port: number
+  wsPort: number
+  remoteDevHost?: string
+  concurrency?: number
+}
+
+export interface BuildCtx {
+  buildId: string
+  argv: Argv
+  cfg: QuartzConfig
+  allSlugs: FullSlug[]
+}

quartz/util/escape.ts

@@ -0,0 +1,17 @@
+export const escapeHTML = (unsafe: string) => {
+  return unsafe
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;")
+}
+
+export const unescapeHTML = (html: string) => {
+  return html
+    .replaceAll("&amp;", "&")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#039;", "'")
+}

quartz/util/glob.ts

@@ -0,0 +1,22 @@
+import path from "path"
+import { FilePath } from "./path"
+import { globby } from "globby"
+
+export function toPosixPath(fp: string): string {
+  return fp.split(path.sep).join("/")
+}
+
+export async function glob(
+  pattern: string,
+  cwd: string,
+  ignorePatterns: string[],
+): Promise<FilePath[]> {
+  const fps = (
+    await globby(pattern, {
+      cwd,
+      ignore: ignorePatterns,
+      gitignore: true,
+    })
+  ).map(toPosixPath)
+  return fps as FilePath[]
+}

quartz/util/jsx.tsx

@@ -0,0 +1,27 @@
+import { Components, Jsx, toJsxRuntime } from "hast-util-to-jsx-runtime"
+import { Node, Root } from "hast"
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime"
+import { trace } from "./trace"
+import { type FilePath } from "./path"
+
+const customComponents: Components = {
+  table: (props) => (
+    <div class="table-container">
+      <table {...props} />
+    </div>
+  ),
+}
+
+export function htmlToJsx(fp: FilePath, tree: Node) {
+  try {
+    return toJsxRuntime(tree as Root, {
+      Fragment,
+      jsx: jsx as Jsx,
+      jsxs: jsxs as Jsx,
+      elementAttributeNameCase: "html",
+      components: customComponents,
+    })
+  } catch (e) {
+    trace(`Failed to parse Markdown in \`${fp}\` into JSX`, e as Error)
+  }
+}

quartz/util/lang.ts

@@ -0,0 +1,13 @@
+export function capitalize(s: string): string {
+  return s.substring(0, 1).toUpperCase() + s.substring(1)
+}
+
+export function classNames(
+  displayClass?: "mobile-only" | "desktop-only",
+  ...classes: string[]
+): string {
+  if (displayClass) {
+    classes.push(displayClass)
+  }
+  return classes.join(" ")
+}

quartz/util/log.ts

@@ -0,0 +1,28 @@
+import { Spinner } from "cli-spinner"
+
+export class QuartzLogger {
+  verbose: boolean
+  spinner: Spinner | undefined
+  constructor(verbose: boolean) {
+    this.verbose = verbose
+  }
+
+  start(text: string) {
+    if (this.verbose) {
+      console.log(text)
+    } else {
+      this.spinner = new Spinner(`%s ${text}`)
+      this.spinner.setSpinnerString(18)
+      this.spinner.start()
+    }
+  }
+
+  end(text?: string) {
+    if (!this.verbose) {
+      this.spinner!.stop(true)
+    }
+    if (text) {
+      console.log(text)
+    }
+  }
+}

quartz/util/og.tsx

@@ -0,0 +1,202 @@
+import { FontWeight, SatoriOptions } from "satori/wasm"
+import { GlobalConfiguration } from "../cfg"
+import { QuartzPluginData } from "../plugins/vfile"
+import { JSXInternal } from "preact/src/jsx"
+import { ThemeKey } from "./theme"
+
+/**
+ * Get an array of `FontOptions` (for satori) given google font names
+ * @param headerFontName name of google font used for header
+ * @param bodyFontName name of google font used for body
+ * @returns FontOptions for header and body
+ */
+export async function getSatoriFont(headerFontName: string, bodyFontName: string) {
+  const headerWeight = 700 as FontWeight
+  const bodyWeight = 400 as FontWeight
+
+  // Fetch fonts
+  const headerFont = await fetchTtf(headerFontName, headerWeight)
+  const bodyFont = await fetchTtf(bodyFontName, bodyWeight)
+
+  // Convert fonts to satori font format and return
+  const fonts: SatoriOptions["fonts"] = [
+    { name: headerFontName, data: headerFont, weight: headerWeight, style: "normal" },
+    { name: bodyFontName, data: bodyFont, weight: bodyWeight, style: "normal" },
+  ]
+  return fonts
+}
+
+/**
+ * Get the `.ttf` file of a google font
+ * @param fontName name of google font
+ * @param weight what font weight to fetch font
+ * @returns `.ttf` file of google font
+ */
+async function fetchTtf(fontName: string, weight: FontWeight): Promise<ArrayBuffer> {
+  try {
+    // Get css file from google fonts
+    const cssResponse = await fetch(
+      `https://fonts.googleapis.com/css2?family=${fontName}:wght@${weight}`,
+    )
+    const css = await cssResponse.text()
+
+    // Extract .ttf url from css file
+    const urlRegex = /url\((https:\/\/fonts.gstatic.com\/s\/.*?.ttf)\)/g
+    const match = urlRegex.exec(css)
+
+    if (!match) {
+      throw new Error("Could not fetch font")
+    }
+
+    // Retrieve font data as ArrayBuffer
+    const fontResponse = await fetch(match[1])
+
+    // fontData is an ArrayBuffer containing the .ttf file data (get match[1] due to google fonts response format, always contains link twice, but second entry is the "raw" link)
+    const fontData = await fontResponse.arrayBuffer()
+
+    return fontData
+  } catch (error) {
+    throw new Error(`Error fetching font: ${error}`)
+  }
+}
+
+export type SocialImageOptions = {
+  /**
+   * What color scheme to use for image generation (uses colors from config theme)
+   */
+  colorScheme: ThemeKey
+  /**
+   * Height to generate image with in pixels (should be around 630px)
+   */
+  height: number
+  /**
+   * Width to generate image with in pixels (should be around 1200px)
+   */
+  width: number
+  /**
+   * Whether to use the auto generated image for the root path ("/", when set to false) or the default og image (when set to true).
+   */
+  excludeRoot: boolean
+  /**
+   * JSX to use for generating image. See satori docs for more info (https://github.com/vercel/satori)
+   * @param cfg global quartz config
+   * @param userOpts options that can be set by user
+   * @param title title of current page
+   * @param description description of current page
+   * @param fonts global font that can be used for styling
+   * @param fileData full fileData of current page
+   * @returns prepared jsx to be used for generating image
+   */
+  imageStructure: (
+    cfg: GlobalConfiguration,
+    userOpts: UserOpts,
+    title: string,
+    description: string,
+    fonts: SatoriOptions["fonts"],
+    fileData: QuartzPluginData,
+  ) => JSXInternal.Element
+}
+
+export type UserOpts = Omit<SocialImageOptions, "imageStructure">
+
+export type ImageOptions = {
+  /**
+   * what title to use as header in image
+   */
+  title: string
+  /**
+   * what description to use as body in image
+   */
+  description: string
+  /**
+   * what fileName to use when writing to disk
+   */
+  fileName: string
+  /**
+   * what directory to store image in
+   */
+  fileDir: string
+  /**
+   * what file extension to use (should be `webp` unless you also change sharp conversion)
+   */
+  fileExt: string
+  /**
+   * header + body font to be used when generating satori image (as promise to work around sync in component)
+   */
+  fontsPromise: Promise<SatoriOptions["fonts"]>
+  /**
+   * `GlobalConfiguration` of quartz (used for theme/typography)
+   */
+  cfg: GlobalConfiguration
+  /**
+   * full file data of current page
+   */
+  fileData: QuartzPluginData
+}
+
+// This is the default template for generated social image.
+export const defaultImage: SocialImageOptions["imageStructure"] = (
+  cfg: GlobalConfiguration,
+  { colorScheme }: UserOpts,
+  title: string,
+  description: string,
+  fonts: SatoriOptions["fonts"],
+  _fileData: QuartzPluginData,
+) => {
+  // How many characters are allowed before switching to smaller font
+  const fontBreakPoint = 22
+  const useSmallerFont = title.length > fontBreakPoint
+
+  // Setup to access image
+  const iconPath = `https://${cfg.baseUrl}/static/icon.png`
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: "center",
+        alignItems: "center",
+        height: "100%",
+        width: "100%",
+        backgroundColor: cfg.theme.colors[colorScheme].light,
+        gap: "2rem",
+        paddingTop: "1.5rem",
+        paddingBottom: "1.5rem",
+        paddingLeft: "5rem",
+        paddingRight: "5rem",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "flex-start",
+          width: "100%",
+          flexDirection: "row",
+          gap: "2.5rem",
+        }}
+      >
+        <img src={iconPath} width={135} height={135} />
+        <p
+          style={{
+            color: cfg.theme.colors[colorScheme].dark,
+            fontSize: useSmallerFont ? 70 : 82,
+            fontFamily: fonts[0].name,
+          }}
+        >
+          {title}
+        </p>
+      </div>
+      <p
+        style={{
+          color: cfg.theme.colors[colorScheme].dark,
+          fontSize: 44,
+          lineClamp: 3,
+          fontFamily: fonts[1].name,
+        }}
+      >
+        {description}
+      </p>
+    </div>
+  )
+}

quartz/util/path.test.ts

@@ -0,0 +1,305 @@
+import test, { describe } from "node:test"
+import * as path from "./path"
+import assert from "node:assert"
+import { FullSlug, TransformOptions } from "./path"
+
+describe("typeguards", () => {
+  test("isSimpleSlug", () => {
+    assert(path.isSimpleSlug(""))
+    assert(path.isSimpleSlug("abc"))
+    assert(path.isSimpleSlug("abc/"))
+    assert(path.isSimpleSlug("notindex"))
+    assert(path.isSimpleSlug("notindex/def"))
+
+    assert(!path.isSimpleSlug("//"))
+    assert(!path.isSimpleSlug("index"))
+    assert(!path.isSimpleSlug("https://example.com"))
+    assert(!path.isSimpleSlug("/abc"))
+    assert(!path.isSimpleSlug("abc/index"))
+    assert(!path.isSimpleSlug("abc#anchor"))
+    assert(!path.isSimpleSlug("abc?query=1"))
+    assert(!path.isSimpleSlug("index.md"))
+    assert(!path.isSimpleSlug("index.html"))
+  })
+
+  test("isRelativeURL", () => {
+    assert(path.isRelativeURL("."))
+    assert(path.isRelativeURL(".."))
+    assert(path.isRelativeURL("./abc/def"))
+    assert(path.isRelativeURL("./abc/def#an-anchor"))
+    assert(path.isRelativeURL("./abc/def?query=1#an-anchor"))
+    assert(path.isRelativeURL("../abc/def"))
+    assert(path.isRelativeURL("./abc/def.pdf"))
+
+    assert(!path.isRelativeURL("abc"))
+    assert(!path.isRelativeURL("/abc/def"))
+    assert(!path.isRelativeURL(""))
+    assert(!path.isRelativeURL("./abc/def.html"))
+    assert(!path.isRelativeURL("./abc/def.md"))
+  })
+
+  test("isFullSlug", () => {
+    assert(path.isFullSlug("index"))
+    assert(path.isFullSlug("abc/def"))
+    assert(path.isFullSlug("html.energy"))
+    assert(path.isFullSlug("test.pdf"))
+
+    assert(!path.isFullSlug("."))
+    assert(!path.isFullSlug("./abc/def"))
+    assert(!path.isFullSlug("../abc/def"))
+    assert(!path.isFullSlug("abc/def#anchor"))
+    assert(!path.isFullSlug("abc/def?query=1"))
+    assert(!path.isFullSlug("note with spaces"))
+  })
+
+  test("isFilePath", () => {
+    assert(path.isFilePath("content/index.md"))
+    assert(path.isFilePath("content/test.png"))
+    assert(!path.isFilePath("../test.pdf"))
+    assert(!path.isFilePath("content/test"))
+    assert(!path.isFilePath("./content/test"))
+  })
+})
+
+describe("transforms", () => {
+  function asserts<Inp, Out>(
+    pairs: [string, string][],
+    transform: (inp: Inp) => Out,
+    checkPre: (x: any) => x is Inp,
+    checkPost: (x: any) => x is Out,
+  ) {
+    for (const [inp, expected] of pairs) {
+      assert(checkPre(inp), `${inp} wasn't the expected input type`)
+      const actual = transform(inp)
+      assert.strictEqual(
+        actual,
+        expected,
+        `after transforming ${inp}, '${actual}' was not '${expected}'`,
+      )
+      assert(checkPost(actual), `${actual} wasn't the expected output type`)
+    }
+  }
+
+  test("simplifySlug", () => {
+    asserts(
+      [
+        ["index", "/"],
+        ["abc", "abc"],
+        ["abc/index", "abc/"],
+        ["abc/def", "abc/def"],
+      ],
+      path.simplifySlug,
+      path.isFullSlug,
+      path.isSimpleSlug,
+    )
+  })
+
+  test("slugifyFilePath", () => {
+    asserts(
+      [
+        ["content/index.md", "content/index"],
+        ["content/index.html", "content/index"],
+        ["content/_index.md", "content/index"],
+        ["/content/index.md", "content/index"],
+        ["content/cool.png", "content/cool.png"],
+        ["index.md", "index"],
+        ["test.mp4", "test.mp4"],
+        ["note with spaces.md", "note-with-spaces"],
+        ["notes.with.dots.md", "notes.with.dots"],
+        ["test/special chars?.md", "test/special-chars"],
+        ["test/special chars #3.md", "test/special-chars-3"],
+        ["cool/what about r&d?.md", "cool/what-about-r-and-d"],
+      ],
+      path.slugifyFilePath,
+      path.isFilePath,
+      path.isFullSlug,
+    )
+  })
+
+  test("transformInternalLink", () => {
+    asserts(
+      [
+        ["", "."],
+        [".", "."],
+        ["./", "./"],
+        ["./index", "./"],
+        ["./index#abc", "./#abc"],
+        ["./index.html", "./"],
+        ["./index.md", "./"],
+        ["./index.css", "./index.css"],
+        ["content", "./content"],
+        ["content/test.md", "./content/test"],
+        ["content/test.pdf", "./content/test.pdf"],
+        ["./content/test.md", "./content/test"],
+        ["../content/test.md", "../content/test"],
+        ["tags/", "./tags/"],
+        ["/tags/", "./tags/"],
+        ["content/with spaces", "./content/with-spaces"],
+        ["content/with spaces/index", "./content/with-spaces/"],
+        ["content/with spaces#and Anchor!", "./content/with-spaces#and-anchor"],
+      ],
+      path.transformInternalLink,
+      (_x: string): _x is string => true,
+      path.isRelativeURL,
+    )
+  })
+
+  test("pathToRoot", () => {
+    asserts(
+      [
+        ["index", "."],
+        ["abc", "."],
+        ["abc/def", ".."],
+        ["abc/def/ghi", "../.."],
+        ["abc/def/index", "../.."],
+      ],
+      path.pathToRoot,
+      path.isFullSlug,
+      path.isRelativeURL,
+    )
+  })
+
+  test("joinSegments", () => {
+    assert.strictEqual(path.joinSegments("a", "b"), "a/b")
+    assert.strictEqual(path.joinSegments("a/", "b"), "a/b")
+    assert.strictEqual(path.joinSegments("a", "b/"), "a/b/")
+    assert.strictEqual(path.joinSegments("a/", "b/"), "a/b/")
+
+    // preserve leading and trailing slashes
+    assert.strictEqual(path.joinSegments("/a", "b"), "/a/b")
+    assert.strictEqual(path.joinSegments("/a/", "b"), "/a/b")
+    assert.strictEqual(path.joinSegments("/a", "b/"), "/a/b/")
+    assert.strictEqual(path.joinSegments("/a/", "b/"), "/a/b/")
+
+    // lone slash
+    assert.strictEqual(path.joinSegments("/a/", "b", "/"), "/a/b/")
+    assert.strictEqual(path.joinSegments("a/", "b" + "/"), "a/b/")
+
+    // works with protocol specifiers
+    assert.strictEqual(path.joinSegments("https://example.com", "a"), "https://example.com/a")
+    assert.strictEqual(path.joinSegments("https://example.com/", "a"), "https://example.com/a")
+    assert.strictEqual(path.joinSegments("https://example.com", "a/"), "https://example.com/a/")
+    assert.strictEqual(path.joinSegments("https://example.com/", "a/"), "https://example.com/a/")
+  })
+})
+
+describe("link strategies", () => {
+  const allSlugs = [
+    "a/b/c",
+    "a/b/d",
+    "a/b/index",
+    "e/f",
+    "e/g/h",
+    "index",
+    "a/test.png",
+  ] as FullSlug[]
+
+  describe("absolute", () => {
+    const opts: TransformOptions = {
+      strategy: "absolute",
+      allSlugs,
+    }
+
+    test("from a/b/c", () => {
+      const cur = "a/b/c" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "a/b/d", opts), "../../a/b/d")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "../../a/b/")
+      assert.strictEqual(path.transformLink(cur, "e/f", opts), "../../e/f")
+      assert.strictEqual(path.transformLink(cur, "e/g/h", opts), "../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "../../")
+      assert.strictEqual(path.transformLink(cur, "index.png", opts), "../../index.png")
+      assert.strictEqual(path.transformLink(cur, "index#abc", opts), "../../#abc")
+      assert.strictEqual(path.transformLink(cur, "tag/test", opts), "../../tag/test")
+      assert.strictEqual(path.transformLink(cur, "a/b/c#test", opts), "../../a/b/c#test")
+      assert.strictEqual(path.transformLink(cur, "a/test.png", opts), "../../a/test.png")
+    })
+
+    test("from a/b/index", () => {
+      const cur = "a/b/index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "a/b/d", opts), "../../a/b/d")
+      assert.strictEqual(path.transformLink(cur, "a/b", opts), "../../a/b")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "../../")
+    })
+
+    test("from index", () => {
+      const cur = "index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "index", opts), "./")
+      assert.strictEqual(path.transformLink(cur, "a/b/c", opts), "./a/b/c")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "./a/b/")
+    })
+  })
+
+  describe("shortest", () => {
+    const opts: TransformOptions = {
+      strategy: "shortest",
+      allSlugs,
+    }
+
+    test("from a/b/c", () => {
+      const cur = "a/b/c" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "d", opts), "../../a/b/d")
+      assert.strictEqual(path.transformLink(cur, "h", opts), "../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "../../a/b/")
+      assert.strictEqual(path.transformLink(cur, "a/b/index.png", opts), "../../a/b/index.png")
+      assert.strictEqual(path.transformLink(cur, "a/b/index#abc", opts), "../../a/b/#abc")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "../../")
+      assert.strictEqual(path.transformLink(cur, "index.png", opts), "../../index.png")
+      assert.strictEqual(path.transformLink(cur, "test.png", opts), "../../a/test.png")
+      assert.strictEqual(path.transformLink(cur, "index#abc", opts), "../../#abc")
+    })
+
+    test("from a/b/index", () => {
+      const cur = "a/b/index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "d", opts), "../../a/b/d")
+      assert.strictEqual(path.transformLink(cur, "h", opts), "../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "../../a/b/")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "../../")
+    })
+
+    test("from index", () => {
+      const cur = "index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "d", opts), "./a/b/d")
+      assert.strictEqual(path.transformLink(cur, "h", opts), "./e/g/h")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "./a/b/")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "./")
+    })
+  })
+
+  describe("relative", () => {
+    const opts: TransformOptions = {
+      strategy: "relative",
+      allSlugs,
+    }
+
+    test("from a/b/c", () => {
+      const cur = "a/b/c" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "d", opts), "./d")
+      assert.strictEqual(path.transformLink(cur, "index", opts), "./")
+      assert.strictEqual(path.transformLink(cur, "../../../index", opts), "../../../")
+      assert.strictEqual(path.transformLink(cur, "../../../index.png", opts), "../../../index.png")
+      assert.strictEqual(path.transformLink(cur, "../../../index#abc", opts), "../../../#abc")
+      assert.strictEqual(path.transformLink(cur, "../../../", opts), "../../../")
+      assert.strictEqual(
+        path.transformLink(cur, "../../../a/test.png", opts),
+        "../../../a/test.png",
+      )
+      assert.strictEqual(path.transformLink(cur, "../../../e/g/h", opts), "../../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "../../../e/g/h", opts), "../../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "../../../e/g/h#abc", opts), "../../../e/g/h#abc")
+    })
+
+    test("from a/b/index", () => {
+      const cur = "a/b/index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "../../index", opts), "../../")
+      assert.strictEqual(path.transformLink(cur, "../../", opts), "../../")
+      assert.strictEqual(path.transformLink(cur, "../../e/g/h", opts), "../../e/g/h")
+      assert.strictEqual(path.transformLink(cur, "c", opts), "./c")
+    })
+
+    test("from index", () => {
+      const cur = "index" as FullSlug
+      assert.strictEqual(path.transformLink(cur, "e/g/h", opts), "./e/g/h")
+      assert.strictEqual(path.transformLink(cur, "a/b/index", opts), "./a/b/")
+    })
+  })
+})

quartz/util/path.ts

@@ -0,0 +1,311 @@
+import { slug as slugAnchor } from "github-slugger"
+import type { Element as HastElement } from "hast"
+import rfdc from "rfdc"
+
+export const clone = rfdc()
+
+// this file must be isomorphic so it can't use node libs (e.g. path)
+
+export const QUARTZ = "quartz"
+
+/// Utility type to simulate nominal types in TypeScript
+type SlugLike<T> = string & { __brand: T }
+
+/** Cannot be relative and must have a file extension. */
+export type FilePath = SlugLike<"filepath">
+export function isFilePath(s: string): s is FilePath {
+  const validStart = !s.startsWith(".")
+  return validStart && _hasFileExtension(s)
+}
+
+/** Cannot be relative and may not have leading or trailing slashes. It can have `index` as it's last segment. Use this wherever possible is it's the most 'general' interpretation of a slug. */
+export type FullSlug = SlugLike<"full">
+export function isFullSlug(s: string): s is FullSlug {
+  const validStart = !(s.startsWith(".") || s.startsWith("/"))
+  const validEnding = !s.endsWith("/")
+  return validStart && validEnding && !containsForbiddenCharacters(s)
+}
+
+/** 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.length > 1 && s.startsWith("/")))
+  const validEnding = !endsWith(s, "index")
+  return validStart && !containsForbiddenCharacters(s) && validEnding && !_hasFileExtension(s)
+}
+
+/** Can be found on `href`s but can also be constructed for client-side navigation (e.g. search and graph) */
+export type RelativeURL = SlugLike<"relative">
+export function isRelativeURL(s: string): s is RelativeURL {
+  const validStart = /^\.{1,2}/.test(s)
+  const validEnding = !endsWith(s, "index")
+  return validStart && validEnding && ![".md", ".html"].includes(_getFileExtension(s) ?? "")
+}
+
+export function getFullSlug(window: Window): FullSlug {
+  const res = window.document.body.dataset.slug! as FullSlug
+  return res
+}
+
+function sluggify(s: string): string {
+  return s
+    .split("/")
+    .map((segment) =>
+      segment
+        .replace(/\s/g, "-")
+        .replace(/&/g, "-and-")
+        .replace(/%/g, "-percent")
+        .replace(/\?/g, "")
+        .replace(/#/g, ""),
+    )
+    .join("/") // always use / as sep
+    .replace(/\/$/, "")
+}
+
+export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug {
+  fp = stripSlashes(fp) as FilePath
+  let ext = _getFileExtension(fp)
+  const withoutFileExt = fp.replace(new RegExp(ext + "$"), "")
+  if (excludeExt || [".md", ".html", undefined].includes(ext)) {
+    ext = ""
+  }
+
+  let slug = sluggify(withoutFileExt)
+
+  // treat _index as index
+  if (endsWith(slug, "_index")) {
+    slug = slug.replace(/_index$/, "index")
+  }
+
+  return (slug + ext) as FullSlug
+}
+
+export function simplifySlug(fp: FullSlug): SimpleSlug {
+  const res = stripSlashes(trimSuffix(fp, "index"), true)
+  return (res.length === 0 ? "/" : res) as SimpleSlug
+}
+
+export function transformInternalLink(link: string): RelativeURL {
+  let [fplike, anchor] = splitAnchor(decodeURI(link))
+
+  const folderPath = isFolderPath(fplike)
+  let segments = fplike.split("/").filter((x) => x.length > 0)
+  let prefix = segments.filter(isRelativeSegment).join("/")
+  let fp = segments.filter((seg) => !isRelativeSegment(seg) && seg !== "").join("/")
+
+  // manually add ext here as we want to not strip 'index' if it has an extension
+  const simpleSlug = simplifySlug(slugifyFilePath(fp as FilePath))
+  const joined = joinSegments(stripSlashes(prefix), stripSlashes(simpleSlug))
+  const trail = folderPath ? "/" : ""
+  const res = (_addRelativeToStart(joined) + trail + anchor) as 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^="./"], [href^="../"]').forEach((item) =>
+    _rebaseHtmlElement(item, "href", destination),
+  )
+  el.querySelectorAll('[src=""], [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(rawEl: HastElement, curBase: FullSlug, newBase: FullSlug) {
+  const el = clone(rawEl) // clone so we dont modify the original page
+  _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
+    .split("/")
+    .filter((x) => x !== "")
+    .slice(0, -1)
+    .map((_) => "..")
+    .join("/")
+
+  if (rootPath.length === 0) {
+    rootPath = "."
+  }
+
+  return rootPath as RelativeURL
+}
+
+export function resolveRelative(current: FullSlug, target: FullSlug | SimpleSlug): RelativeURL {
+  const res = joinSegments(pathToRoot(current), simplifySlug(target as FullSlug)) as RelativeURL
+  return res
+}
+
+export function splitAnchor(link: string): [string, string] {
+  let [fp, anchor] = link.split("#", 2)
+  if (fp.endsWith(".pdf")) {
+    return [fp, anchor === undefined ? "" : `#${anchor}`]
+  }
+  anchor = anchor === undefined ? "" : "#" + slugAnchor(anchor)
+  return [fp, anchor]
+}
+
+export function slugTag(tag: string) {
+  return tag
+    .split("/")
+    .map((tagSegment) => sluggify(tagSegment))
+    .join("/")
+}
+
+export function joinSegments(...args: string[]): string {
+  if (args.length === 0) {
+    return ""
+  }
+
+  let joined = args
+    .filter((segment) => segment !== "" && segment !== "/")
+    .map((segment) => stripSlashes(segment))
+    .join("/")
+
+  // if the first segment starts with a slash, add it back
+  if (args[0].startsWith("/")) {
+    joined = "/" + joined
+  }
+
+  // if the last segment is a folder, add a trailing slash
+  if (args[args.length - 1].endsWith("/")) {
+    joined = joined + "/"
+  }
+
+  return joined
+}
+
+export function getAllSegmentPrefixes(tags: string): string[] {
+  const segments = tags.split("/")
+  const results: string[] = []
+  for (let i = 0; i < segments.length; i++) {
+    results.push(segments.slice(0, i + 1).join("/"))
+  }
+  return results
+}
+
+export interface TransformOptions {
+  strategy: "absolute" | "relative" | "shortest"
+  allSlugs: FullSlug[]
+}
+
+export function transformLink(src: FullSlug, target: string, opts: TransformOptions): RelativeURL {
+  let targetSlug = transformInternalLink(target)
+
+  if (opts.strategy === "relative") {
+    return targetSlug as RelativeURL
+  } else {
+    const folderTail = isFolderPath(targetSlug) ? "/" : ""
+    const canonicalSlug = stripSlashes(targetSlug.slice(".".length))
+    let [targetCanonical, targetAnchor] = splitAnchor(canonicalSlug)
+
+    if (opts.strategy === "shortest") {
+      // if the file name is unique, then it's just the filename
+      const matchingFileNames = opts.allSlugs.filter((slug) => {
+        const parts = slug.split("/")
+        const fileName = parts.at(-1)
+        return targetCanonical === fileName
+      })
+
+      // only match, just use it
+      if (matchingFileNames.length === 1) {
+        const targetSlug = matchingFileNames[0]
+        return (resolveRelative(src, targetSlug) + targetAnchor) as RelativeURL
+      }
+    }
+
+    // if it's not unique, then it's the absolute path from the vault root
+    return (joinSegments(pathToRoot(src), canonicalSlug) + folderTail) as RelativeURL
+  }
+}
+
+// path helpers
+function isFolderPath(fplike: string): boolean {
+  return (
+    fplike.endsWith("/") ||
+    endsWith(fplike, "index") ||
+    endsWith(fplike, "index.md") ||
+    endsWith(fplike, "index.html")
+  )
+}
+
+export function endsWith(s: string, suffix: string): boolean {
+  return s === suffix || s.endsWith("/" + suffix)
+}
+
+function trimSuffix(s: string, suffix: string): string {
+  if (endsWith(s, suffix)) {
+    s = s.slice(0, -suffix.length)
+  }
+  return s
+}
+
+function containsForbiddenCharacters(s: string): boolean {
+  return s.includes(" ") || s.includes("#") || s.includes("?") || s.includes("&")
+}
+
+function _hasFileExtension(s: string): boolean {
+  return _getFileExtension(s) !== undefined
+}
+
+function _getFileExtension(s: string): string | undefined {
+  return s.match(/\.[A-Za-z0-9]+$/)?.[0]
+}
+
+function isRelativeSegment(s: string): boolean {
+  return /^\.{0,2}$/.test(s)
+}
+
+export function stripSlashes(s: string, onlyStripPrefix?: boolean): string {
+  if (s.startsWith("/")) {
+    s = s.substring(1)
+  }
+
+  if (!onlyStripPrefix && s.endsWith("/")) {
+    s = s.slice(0, -1)
+  }
+
+  return s
+}
+
+function _addRelativeToStart(s: string): string {
+  if (s === "") {
+    s = "."
+  }
+
+  if (!s.startsWith(".")) {
+    s = joinSegments(".", s)
+  }
+
+  return s
+}

quartz/util/perf.ts

@@ -0,0 +1,19 @@
+import chalk from "chalk"
+import pretty from "pretty-time"
+
+export class PerfTimer {
+  evts: { [key: string]: [number, number] }
+
+  constructor() {
+    this.evts = {}
+    this.addEvent("start")
+  }
+
+  addEvent(evtName: string) {
+    this.evts[evtName] = process.hrtime()
+  }
+
+  timeSince(evtName?: string): string {
+    return chalk.yellow(pretty(process.hrtime(this.evts[evtName ?? "start"])))
+  }
+}

quartz/util/resources.tsx

@@ -0,0 +1,65 @@
+import { randomUUID } from "crypto"
+import { JSX } from "preact/jsx-runtime"
+
+export type JSResource = {
+  loadTime: "beforeDOMReady" | "afterDOMReady"
+  moduleType?: "module"
+  spaPreserve?: boolean
+} & (
+  | {
+      src: string
+      contentType: "external"
+    }
+  | {
+      script: string
+      contentType: "inline"
+    }
+)
+
+export type CSSResource = {
+  content: string
+  inline?: boolean
+  spaPreserve?: boolean
+}
+
+export function JSResourceToScriptElement(resource: JSResource, preserve?: boolean): JSX.Element {
+  const scriptType = resource.moduleType ?? "application/javascript"
+  const spaPreserve = preserve ?? resource.spaPreserve
+  if (resource.contentType === "external") {
+    return (
+      <script key={resource.src} src={resource.src} type={scriptType} spa-preserve={spaPreserve} />
+    )
+  } else {
+    const content = resource.script
+    return (
+      <script
+        key={randomUUID()}
+        type={scriptType}
+        spa-preserve={spaPreserve}
+        dangerouslySetInnerHTML={{ __html: content }}
+      ></script>
+    )
+  }
+}
+
+export function CSSResourceToStyleElement(resource: CSSResource, preserve?: boolean): JSX.Element {
+  const spaPreserve = preserve ?? resource.spaPreserve
+  if (resource.inline ?? false) {
+    return <style>{resource.content}</style>
+  } else {
+    return (
+      <link
+        key={resource.content}
+        href={resource.content}
+        rel="stylesheet"
+        type="text/css"
+        spa-preserve={spaPreserve}
+      />
+    )
+  }
+}
+
+export interface StaticResources {
+  css: CSSResource[]
+  js: JSResource[]
+}

quartz/util/sourcemap.ts

@@ -0,0 +1,18 @@
+import fs from "fs"
+import sourceMapSupport from "source-map-support"
+import { fileURLToPath } from "url"
+
+export const options: sourceMapSupport.Options = {
+  // source map hack to get around query param
+  // import cache busting
+  retrieveSourceMap(source) {
+    if (source.includes(".quartz-cache")) {
+      let realSource = fileURLToPath(source.split("?", 2)[0] + ".map")
+      return {
+        map: fs.readFileSync(realSource, "utf8"),
+      }
+    } else {
+      return null
+    }
+  },
+}

quartz/util/theme.ts

@@ -0,0 +1,72 @@
+export interface ColorScheme {
+  light: string
+  lightgray: string
+  gray: string
+  darkgray: string
+  dark: string
+  secondary: string
+  tertiary: string
+  highlight: string
+  textHighlight: string
+}
+
+interface Colors {
+  lightMode: ColorScheme
+  darkMode: ColorScheme
+}
+
+export interface Theme {
+  typography: {
+    header: string
+    body: string
+    code: string
+  }
+  cdnCaching: boolean
+  colors: Colors
+  fontOrigin: "googleFonts" | "local"
+}
+
+export type ThemeKey = keyof Colors
+
+const DEFAULT_SANS_SERIF =
+  '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif'
+const DEFAULT_MONO = "ui-monospace, SFMono-Regular, SF Mono, Menlo, monospace"
+
+export function googleFontHref(theme: Theme) {
+  const { code, header, body } = theme.typography
+  return `https://fonts.googleapis.com/css2?family=${code}&family=${header}:wght@400;700&family=${body}:ital,wght@0,400;0,600;1,400;1,600&display=swap`
+}
+
+export function joinStyles(theme: Theme, ...stylesheet: string[]) {
+  return `
+${stylesheet.join("\n\n")}
+
+:root {
+  --light: ${theme.colors.lightMode.light};
+  --lightgray: ${theme.colors.lightMode.lightgray};
+  --gray: ${theme.colors.lightMode.gray};
+  --darkgray: ${theme.colors.lightMode.darkgray};
+  --dark: ${theme.colors.lightMode.dark};
+  --secondary: ${theme.colors.lightMode.secondary};
+  --tertiary: ${theme.colors.lightMode.tertiary};
+  --highlight: ${theme.colors.lightMode.highlight};
+  --textHighlight: ${theme.colors.lightMode.textHighlight};
+
+  --headerFont: "${theme.typography.header}", ${DEFAULT_SANS_SERIF};
+  --bodyFont: "${theme.typography.body}", ${DEFAULT_SANS_SERIF};
+  --codeFont: "${theme.typography.code}", ${DEFAULT_MONO};
+}
+
+:root[saved-theme="dark"] {
+  --light: ${theme.colors.darkMode.light};
+  --lightgray: ${theme.colors.darkMode.lightgray};
+  --gray: ${theme.colors.darkMode.gray};
+  --darkgray: ${theme.colors.darkMode.darkgray};
+  --dark: ${theme.colors.darkMode.dark};
+  --secondary: ${theme.colors.darkMode.secondary};
+  --tertiary: ${theme.colors.darkMode.tertiary};
+  --highlight: ${theme.colors.darkMode.highlight};
+  --textHighlight: ${theme.colors.darkMode.textHighlight};
+}
+`
+}

quartz/util/trace.ts

@@ -0,0 +1,43 @@
+import chalk from "chalk"
+import process from "process"
+import { isMainThread } from "workerpool"
+
+const rootFile = /.*at file:/
+export function trace(msg: string, err: Error) {
+  let stack = err.stack ?? ""
+
+  const lines: string[] = []
+
+  lines.push("")
+  lines.push(
+    "\n" +
+      chalk.bgRed.black.bold(" ERROR ") +
+      "\n\n" +
+      chalk.red(` ${msg}`) +
+      (err.message.length > 0 ? `: ${err.message}` : ""),
+  )
+
+  let reachedEndOfLegibleTrace = false
+  for (const line of stack.split("\n").slice(1)) {
+    if (reachedEndOfLegibleTrace) {
+      break
+    }
+
+    if (!line.includes("node_modules")) {
+      lines.push(` ${line}`)
+      if (rootFile.test(line)) {
+        reachedEndOfLegibleTrace = true
+      }
+    }
+  }
+
+  const traceMsg = lines.join("\n")
+  if (!isMainThread) {
+    // gather lines and throw
+    throw new Error(traceMsg)
+  } else {
+    // print and exit
+    console.error(traceMsg)
+    process.exit(1)
+  }
+}