base path refactor, more docs

quartz/components/Backlinks.tsx

@@ -1,7 +1,7 @@
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import style from "./styles/backlinks.scss"
 import { relativeToRoot } from "../path"
-import { stripIndex } from "./scripts/util"
+import { clientSideSlug } from "./scripts/util"
 
 function Backlinks({ fileData, allFiles }: QuartzComponentProps) {
   const slug = fileData.slug!
@@ -10,7 +10,7 @@ function Backlinks({ fileData, allFiles }: QuartzComponentProps) {
     <h3>Backlinks</h3>
     <ul class="overflow">
       {backlinkFiles.length > 0 ?
-        backlinkFiles.map(f => <li><a href={stripIndex(relativeToRoot(slug, f.slug!))} class="internal">{f.frontmatter?.title}</a></li>)
+        backlinkFiles.map(f => <li><a href={clientSideSlug(relativeToRoot(slug, f.slug!))} class="internal">{f.frontmatter?.title}</a></li>)
         : <li>No backlinks found</li>}
     </ul>
   </div> 

quartz/components/Head.tsx

@@ -1,14 +1,14 @@
-import { clientSideSlug, resolveToRoot } from "../path"
+import { toServerSlug, pathToRoot } from "../path"
 import { JSResourceToScriptElement } from "../resources"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 
 export default (() => {
   function Head({ fileData, externalResources }: QuartzComponentProps) {
-    const slug = clientSideSlug(fileData.slug!)
+    const slug = toServerSlug(fileData.slug!)
     const title = fileData.frontmatter?.title ?? "Untitled"
     const description = fileData.description ?? "No description provided"
     const { css, js } = externalResources
-    const baseDir = resolveToRoot(slug)
+    const baseDir = pathToRoot(slug)
     const iconPath = baseDir + "/static/icon.png"
     const ogImagePath = baseDir + "/static/og-image.png"
 

quartz/components/PageList.tsx

@@ -1,7 +1,7 @@
 import { relativeToRoot } from "../path"
 import { QuartzPluginData } from "../plugins/vfile"
 import { Date } from "./Date"
-import { stripIndex } from "./scripts/util"
+import { clientSideSlug } from "./scripts/util"
 import { QuartzComponentProps } from "./types"
 
 function byDateAndAlphabetical(f1: QuartzPluginData, f2: QuartzPluginData): number {
@@ -34,7 +34,7 @@ export function PageList({ fileData, allFiles }: QuartzComponentProps) {
             <Date date={page.dates.modified} />
           </p>}
           <div class="desc">
-            <h3><a href={stripIndex(relativeToRoot(slug, pageSlug))} class="internal">{title}</a></h3>
+            <h3><a href={clientSideSlug(relativeToRoot(slug, pageSlug))} class="internal">{title}</a></h3>
           </div>
           <ul class="tags">
             {tags.map(tag => <li><a class="internal" href={relativeToRoot(slug, `tags/${tag}`)}>#{tag}</a></li>)}

quartz/components/PageTitle.tsx

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

quartz/components/TagList.tsx

@@ -1,11 +1,11 @@
-import { resolveToRoot } from "../path"
+import { pathToRoot } from "../path"
 import { QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import { slug as slugAnchor } from 'github-slugger'
 
 function TagList({ fileData }: QuartzComponentProps) {
   const tags = fileData.frontmatter?.tags
   const slug = fileData.slug!
-  const baseDir = resolveToRoot(slug)
+  const baseDir = pathToRoot(slug)
   if (tags && tags.length > 0) {
     return <ul class="tags">{tags.map(tag => {
       const display = `#${tag}`

quartz/components/pages/FolderContent.tsx

@@ -5,11 +5,11 @@ import path from "path"
 
 import style from '../styles/listPage.scss'
 import { PageList } from "../PageList"
-import { clientSideSlug } from "../../path"
+import { toServerSlug } from "../../path"
 
 function FolderContent(props: QuartzComponentProps) {
   const { tree, fileData, allFiles } = props
-  const folderSlug = clientSideSlug(fileData.slug!)
+  const folderSlug = toServerSlug(fileData.slug!)
   const allPagesInFolder = allFiles.filter(file => {
     const fileSlug = file.slug ?? ""
     const prefixed = fileSlug.startsWith(folderSlug)

quartz/components/pages/TagContent.tsx

@@ -3,14 +3,14 @@ import { Fragment, jsx, jsxs } from 'preact/jsx-runtime'
 import { toJsxRuntime } from "hast-util-to-jsx-runtime"
 import style from '../styles/listPage.scss'
 import { PageList } from "../PageList"
-import { clientSideSlug } from "../../path"
+import { toServerSlug } from "../../path"
 
 function TagContent(props: QuartzComponentProps) {
   const { tree, fileData, allFiles } = props
   const slug = fileData.slug
 
   if (slug?.startsWith("tags/")) {
-    const tag = clientSideSlug(slug.slice("tags/".length))
+    const tag = toServerSlug(slug.slice("tags/".length))
     const allPagesWithTag = allFiles.filter(file => (file.frontmatter?.tags ?? []).includes(tag))
     const listProps = {
       ...props,

quartz/components/renderPage.tsx

@@ -3,7 +3,7 @@ import { QuartzComponent, QuartzComponentProps } from "./types";
 import HeaderConstructor from "./Header"
 import BodyConstructor from "./Body"
 import { JSResourceToScriptElement, StaticResources } from "../resources";
-import { resolveToRoot } from "../path";
+import { CanonicalSlug, pathToRoot } from "../path";
 
 interface RenderComponents {
   head: QuartzComponent
@@ -15,8 +15,8 @@ interface RenderComponents {
   footer: QuartzComponent,
 }
 
-export function pageResources(slug: string, staticResources: StaticResources): StaticResources {
-  const baseDir = resolveToRoot(slug)
+export function pageResources(slug: CanonicalSlug, staticResources: StaticResources): StaticResources {
+  const baseDir = pathToRoot(slug)
 
   const contentIndexPath = baseDir + "/static/contentIndex.json"
   const contentIndexScript = `const fetchData = fetch(\`${contentIndexPath}\`).then(data => data.json())`
@@ -32,7 +32,7 @@ export function pageResources(slug: string, staticResources: StaticResources): S
   }
 }
 
-export function renderPage(slug: string, componentData: QuartzComponentProps, components: RenderComponents, pageResources: StaticResources): string {
+export function renderPage(slug: CanonicalSlug, componentData: QuartzComponentProps, components: RenderComponents, pageResources: StaticResources): string {
   const { head: Head, header, beforeBody, pageBody: Content, left, right, footer: Footer } = components
   const Header = HeaderConstructor()
   const Body = BodyConstructor()

quartz/components/scripts/graph.inline.ts

@@ -1,24 +1,25 @@
 import { ContentDetails } from "../../plugins/emitters/contentIndex"
 import * as d3 from 'd3'
-import { registerEscapeHandler, relative, removeAllChildren } from "./util"
+import { registerEscapeHandler, clientSideRelativePath, removeAllChildren } from "./util"
+import { CanonicalSlug } from "../../path"
 
 type NodeData = {
-  id: string,
+  id: CanonicalSlug,
   text: string,
   tags: string[]
 } & d3.SimulationNodeDatum
 
 type LinkData = {
-  source: string,
-  target: string
+  source: CanonicalSlug,
+  target: CanonicalSlug
 }
 
 const localStorageKey = "graph-visited"
-function getVisited(): Set<string> {
+function getVisited(): Set<CanonicalSlug> {
   return new Set(JSON.parse(localStorage.getItem(localStorageKey) ?? "[]"))
 }
 
-function addToVisited(slug: string) {
+function addToVisited(slug: CanonicalSlug) {
   const visited = getVisited()
   visited.add(slug)
   localStorage.setItem(localStorageKey, JSON.stringify([...visited]))
@@ -167,7 +168,7 @@ async function renderGraph(container: string, slug: string) {
     .attr("fill", color)
     .style("cursor", "pointer")
     .on("click", (_, d) => {
-      const targ = relative(slug, d.id)
+      const targ = clientSideRelativePath(slug, d.id)
       window.spaNavigate(new URL(targ))
     })
     .on("mouseover", function(_, d) {

quartz/components/scripts/search.inline.ts

@@ -1,9 +1,10 @@
 import { Document } from "flexsearch"
 import { ContentDetails } from "../../plugins/emitters/contentIndex"
-import { registerEscapeHandler, relative, removeAllChildren } from "./util"
+import { registerEscapeHandler, clientSideRelativePath, removeAllChildren } from "./util"
+import { CanonicalSlug } from "../../path"
 
 interface Item {
-  slug: string,
+  slug: CanonicalSlug,
   title: string,
   content: string,
 }
@@ -100,7 +101,7 @@ document.addEventListener("nav", async (e: unknown) => {
     }
   }
 
-  const formatForDisplay = (term: string, slug: string) => ({
+  const formatForDisplay = (term: string, slug: CanonicalSlug) => ({
     slug,
     title: highlight(term, data[slug].title ?? ""),
     content: highlight(term, data[slug].content ?? "", true),
@@ -112,7 +113,7 @@ document.addEventListener("nav", async (e: unknown) => {
     button.id = slug
     button.innerHTML = `<h3>${title}</h3><p>${content}</p>`
     button.addEventListener('click', () => {
-      const targ = relative(currentSlug, slug)
+      const targ = clientSideRelativePath(currentSlug, slug)
       window.spaNavigate(new URL(targ))
     })
     return button
@@ -142,7 +143,7 @@ document.addEventListener("nav", async (e: unknown) => {
     }
 
     // order titles ahead of content
-    const allIds: Set<string> = new Set([...getByField("title"), ...getByField("content")])
+    const allIds: Set<CanonicalSlug> = new Set([...getByField("title"), ...getByField("content")])
     const finalResults = [...allIds].map(id => formatForDisplay(term, id))
     displayResults(finalResults)
   }
@@ -178,7 +179,7 @@ document.addEventListener("nav", async (e: unknown) => {
 
     for (const [slug, fileData] of Object.entries<ContentDetails>(data)) {
       await index.addAsync(slug, {
-        slug,
+        slug: slug as CanonicalSlug,
         title: fileData.title,
         content: fileData.content
       })

quartz/components/scripts/spa.inline.ts

@@ -1,4 +1,5 @@
 import micromorph from "micromorph"
+import { CanonicalSlug, RelativeURL } from "../../path"
 
 // adapted from `micromorph`
 // https://github.com/natemoo-re/micromorph
@@ -29,7 +30,7 @@ const getOpts = ({ target }: Event): { url: URL, scroll?: boolean } | undefined
   return { url: new URL(href), scroll: 'routerNoscroll' in a.dataset ? false : undefined }
 }
 
-function notifyNav(url: string) {
+function notifyNav(url: CanonicalSlug) {
   const event: CustomEventMap["nav"] = new CustomEvent("nav", { detail: { url } })
   document.dispatchEvent(event)
 }
@@ -100,7 +101,7 @@ function createRouter() {
   }
 
   return new class Router {
-    go(pathname: string) {
+    go(pathname: RelativeURL) {
       const url = new URL(pathname, window.location.toString())
       return navigate(url, false)
     }

quartz/components/scripts/util.ts

@@ -18,19 +18,6 @@ export function registerEscapeHandler(outsideContainer: HTMLElement | null, cb:
   document.addEventListener('keydown', esc)
 }
 
-export function stripIndex(s: string): string {
-  return s.endsWith("index") ? s.slice(0, -"index".length) : s
-}
-
-export function relative(from: string, to: string) {
-  from = encodeURI(stripIndex(from))
-  to = encodeURI(stripIndex(to))
-  const start = [location.protocol, '//', location.host, location.pathname].join('')
-  const trimEnd = from.length === 0 ? start.length : -from.length
-  const url = start.slice(0, trimEnd) + to
-  return url
-}
-
 export function removeAllChildren(node: HTMLElement) {
   while (node.firstChild) {
     node.removeChild(node.firstChild)

quartz/components/styles/backlinks.scss

@@ -1,4 +1,6 @@
 .backlinks {
+  position: relative;
+
   & > h3 {
     font-size: 1rem;
     margin: 0;