base path refactor, more docs

quartz/plugins/emitters/aliases.ts

@@ -1,4 +1,4 @@
-import { relativeToRoot } from "../../path"
+import { CanonicalSlug, FilePath, ServerSlug, relativeToRoot } from "../../path"
 import { QuartzEmitterPlugin } from "../types"
 import path from 'path'
 
@@ -7,14 +7,14 @@ export const AliasRedirects: QuartzEmitterPlugin = () => ({
   getQuartzComponents() {
     return []
   },
-  async emit(contentFolder, _cfg, content, _resources, emit): Promise<string[]> {
-    const fps: string[] = []
+  async emit(contentFolder, _cfg, content, _resources, emit): Promise<FilePath[]> {
+    const fps: FilePath[] = []
 
     for (const [_tree, file] of content) {
       const ogSlug = file.data.slug!
       const dir = path.relative(contentFolder, file.dirname ?? contentFolder)
 
-      let aliases: string[] = []
+      let aliases: CanonicalSlug[] = []
       if (file.data.frontmatter?.aliases) {
         aliases = file.data.frontmatter?.aliases
       } else if (file.data.frontmatter?.alias) {
@@ -22,11 +22,11 @@ export const AliasRedirects: QuartzEmitterPlugin = () => ({
       }
 
       for (const alias of aliases) {
-        const slug = alias.startsWith("/")
+        const slug = (alias.startsWith("/")
           ? alias
-          : path.posix.join(dir, alias)
+          : path.posix.join(dir, alias)) as ServerSlug
 
-        const fp = slug + ".html"
+        const fp = slug + ".html" as FilePath
         const redirUrl = relativeToRoot(slug, ogSlug)
         await emit({
           content: `

quartz/plugins/emitters/contentIndex.ts

@@ -1,11 +1,12 @@
 import { GlobalConfiguration } from "../../cfg"
+import { CanonicalSlug, ClientSlug } from "../../path"
 import { QuartzEmitterPlugin } from "../types"
 import path from "path"
 
-export type ContentIndex = Map<string, ContentDetails>
+export type ContentIndex = Map<CanonicalSlug, ContentDetails>
 export type ContentDetails = {
   title: string,
-  links: string[],
+  links: CanonicalSlug[],
   tags: string[],
   content: string,
   date?: Date,
@@ -25,8 +26,8 @@ const defaultOptions: Options = {
 }
 
 function generateSiteMap(cfg: GlobalConfiguration, idx: ContentIndex): string {
-  const base = cfg.canonicalUrl ?? ""
-  const createURLEntry = (slug: string, content: ContentDetails): string => `<url>
+  const base = cfg.baseUrl ?? ""
+  const createURLEntry = (slug: CanonicalSlug, content: ContentDetails): string => `<url>
     <loc>https://${base}/${slug}</loc>
     <lastmod>${content.date?.toISOString()}</lastmod>
   </url>`
@@ -35,10 +36,10 @@ function generateSiteMap(cfg: GlobalConfiguration, idx: ContentIndex): string {
 }
 
 function generateRSSFeed(cfg: GlobalConfiguration, idx: ContentIndex): string {
-  const base = cfg.canonicalUrl ?? ""
-  const root = `https://${base}`
+  const base = cfg.baseUrl ?? ""
+  const root = `https://${base}` as ClientSlug
 
-  const createURLEntry = (slug: string, content: ContentDetails): string => `<items>
+  const createURLEntry = (slug: CanonicalSlug, content: ContentDetails): string => `<items>
     <title>${content.title}</title>
     <link>${root}/${slug}</link>
     <guid>${root}/${slug}</guid>

quartz/plugins/emitters/contentPage.tsx

@@ -4,6 +4,7 @@ import HeaderConstructor from "../../components/Header"
 import BodyConstructor from "../../components/Body"
 import { pageResources, renderPage } from "../../components/renderPage"
 import { FullPageLayout } from "../../cfg"
+import { FilePath } from "../../path"
 
 export const ContentPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
   if (!opts) {
@@ -19,8 +20,8 @@ export const ContentPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
     getQuartzComponents() {
       return [Head, Header, Body, ...header, ...beforeBody, Content, ...left, ...right, Footer]
     },
-    async emit(_contentDir, cfg, content, resources, emit): Promise<string[]> {
-      const fps: string[] = []
+    async emit(_contentDir, cfg, content, resources, emit): Promise<FilePath[]> {
+      const fps: FilePath[] = []
       const allFiles = content.map(c => c[1].data)
       for (const [tree, file] of content) {
         const slug = file.data.slug!
@@ -41,7 +42,7 @@ export const ContentPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
           externalResources
         )
 
-        const fp = file.data.slug + ".html"
+        const fp = file.data.slug + ".html" as FilePath
         await emit({
           content,
           slug: file.data.slug!,

quartz/plugins/emitters/folderPage.tsx

@@ -6,7 +6,7 @@ import { pageResources, renderPage } from "../../components/renderPage"
 import { ProcessedContent, defaultProcessedContent } from "../vfile"
 import { FullPageLayout } from "../../cfg"
 import path from "path"
-import { clientSideSlug } from "../../path"
+import { FilePath, toServerSlug } from "../../path"
 
 export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
   if (!opts) {
@@ -22,7 +22,7 @@ export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
     getQuartzComponents() {
       return [Head, Header, Body, ...header, ...beforeBody, Content, ...left, ...right, Footer]
     },
-    async emit(_contentDir, cfg, content, resources, emit): Promise<string[]> {
+    async emit(_contentDir, cfg, content, resources, emit): Promise<FilePath[]> {
       const fps: string[] = []
       const allFiles = content.map(c => c[1].data)
 
@@ -37,7 +37,7 @@ export const FolderPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
       ])))
 
       for (const [tree, file] of content) {
-        const slug = clientSideSlug(file.data.slug!)
+        const slug = toServerSlug(file.data.slug!)
         if (folders.has(slug)) {
           folderDescriptions[slug] = [tree, file]
         }

quartz/plugins/emitters/tagPage.tsx

@@ -5,7 +5,7 @@ import BodyConstructor from "../../components/Body"
 import { pageResources, renderPage } from "../../components/renderPage"
 import { ProcessedContent, defaultProcessedContent } from "../vfile"
 import { FullPageLayout } from "../../cfg"
-import { clientSideSlug } from "../../path"
+import { FilePath, ServerSlug, toServerSlug } from "../../path"
 
 export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
   if (!opts) {
@@ -21,17 +21,17 @@ export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
     getQuartzComponents() {
       return [Head, Header, Body, ...header, ...beforeBody, Content, ...left, ...right, Footer]
     },
-    async emit(_contentDir, cfg, content, resources, emit): Promise<string[]> {
-      const fps: string[] = []
+    async emit(_contentDir, cfg, content, resources, emit): Promise<FilePath[]> {
+      const fps: FilePath[] = []
       const allFiles = content.map(c => c[1].data)
 
       const tags: Set<string> = new Set(allFiles.flatMap(data => data.frontmatter?.tags ?? []))
       const tagDescriptions: Record<string, ProcessedContent> = Object.fromEntries([...tags].map(tag => ([
-        tag, defaultProcessedContent({ slug: `tags/${tag}`, frontmatter: { title: `Tag: ${tag}`, tags: [] } })
+        tag, defaultProcessedContent({ slug: `tags/${tag}` as ServerSlug, frontmatter: { title: `Tag: ${tag}`, tags: [] } })
       ])))
 
       for (const [tree, file] of content) {
-        const slug = clientSideSlug(file.data.slug!)
+        const slug = toServerSlug(file.data.slug!)
         if (slug.startsWith("tags/")) {
           const tag = slug.slice("tags/".length)
           if (tags.has(tag)) {
@@ -60,7 +60,7 @@ export const TagPage: QuartzEmitterPlugin<FullPageLayout> = (opts) => {
           externalResources
         )
 
-        const fp = file.data.slug + ".html"
+        const fp = file.data.slug + ".html" as FilePath
         await emit({
           content,
           slug: file.data.slug!,

quartz/plugins/index.ts

@@ -4,6 +4,7 @@ import { StaticResources } from '../resources'
 import { joinStyles } from '../theme'
 import { EmitCallback, PluginTypes } from './types'
 import styles from '../styles/base.scss'
+import { FilePath, ServerSlug } from '../path'
 
 export type ComponentResources = {
   css: string[],
@@ -51,7 +52,7 @@ function joinScripts(scripts: string[]): string {
   return scripts.map(script => `(function () {${script}})();`).join("\n")
 }
 
-export async function emitComponentResources(cfg: GlobalConfiguration, res: ComponentResources, emit: EmitCallback): Promise<string[]> {
+export async function emitComponentResources(cfg: GlobalConfiguration, res: ComponentResources, emit: EmitCallback): Promise<FilePath[]> {
   const fps = await Promise.all([
     emit({
       slug: "index",
@@ -99,8 +100,8 @@ export * from './emitters'
 declare module 'vfile' {
   // inserted in processors.ts
   interface DataMap {
-    slug: string
-    allSlugs: string[]
-    filePath: string
+    slug: ServerSlug
+    allSlugs: ServerSlug[]
+    filePath: FilePath
   }
 }

quartz/plugins/transformers/links.ts

@@ -1,5 +1,5 @@
 import { QuartzTransformerPlugin } from "../types"
-import { clientSideSlug, relative, relativeToRoot, slugify, trimPathSuffix } from "../../path"
+import { CanonicalSlug, transformInternalLink } from "../../path"
 import path from "path"
 import { visit } from 'unist-util-visit'
 import isAbsoluteUrl from "is-absolute-url"
@@ -27,9 +27,9 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
     htmlPlugins() {
       return [() => {
         return (tree, file) => {
-          const curSlug = clientSideSlug(file.data.slug!)
+          const curSlug = file.data.slug!
           const transformLink = (target: string) => {
-            const targetSlug = clientSideSlug(slugify(decodeURI(target).trim()))
+            const targetSlug = transformInternalLink(target) 
             if (opts.markdownLinkResolution === 'relative' && !path.isAbsolute(targetSlug)) {
               return './' + relative(curSlug, targetSlug)
             } else if (opts.markdownLinkResolution === 'shortest') {
@@ -38,13 +38,13 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
 
               // if the file name is unique, then it's just the filename
               const matchingFileNames = allSlugs.filter(slug => {
-                const parts = clientSideSlug(slug).split(path.posix.sep)
+                const parts = toServerSlug(slug).split(path.posix.sep)
                 const fileName = parts.at(-1)
                 return targetSlug === fileName
               })
 
               if (matchingFileNames.length === 1) {
-                const targetSlug = clientSideSlug(matchingFileNames[0])
+                const targetSlug = toServerSlug(matchingFileNames[0])
                 return './' + relativeToRoot(curSlug, targetSlug)
               }
 
@@ -55,7 +55,7 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
             return './' + relativeToRoot(curSlug, targetSlug)
           }
 
-          const outgoing: Set<string> = new Set()
+          const outgoing: Set<CanonicalSlug> = new Set()
           visit(tree, 'element', (node, _index, _parent) => {
             // rewrite all links
             if (
@@ -113,6 +113,6 @@ export const CrawlLinks: QuartzTransformerPlugin<Partial<Options> | undefined> =
 
 declare module 'vfile' {
   interface DataMap {
-    links: string[]
+    links: CanonicalSlug[]
   }
 }

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 { slug as slugAnchor } from 'github-slugger'
+import { CanonicalSlug } from "../../path"
 
 export interface Options {
   maxDepth: 1 | 2 | 3 | 4 | 5 | 6,
@@ -19,7 +20,7 @@ const defaultOptions: Options = {
 interface TocEntry {
   depth: number,
   text: string,
-  slug: string
+  slug: CanonicalSlug
 }
 
 export const TableOfContents: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {

quartz/plugins/types.ts

@@ -3,6 +3,7 @@ import { StaticResources } from "../resources"
 import { ProcessedContent } from "./vfile"
 import { GlobalConfiguration } from "../cfg"
 import { QuartzComponent } from "../components/types"
+import { FilePath, ServerSlug } from "../path"
 
 export interface PluginTypes {
   transformers: QuartzTransformerPluginInstance[],
@@ -29,14 +30,14 @@ export type QuartzFilterPluginInstance = {
 export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzEmitterPluginInstance 
 export type QuartzEmitterPluginInstance = {
   name: string
-  emit(contentDir: string, cfg: GlobalConfiguration, content: ProcessedContent[], resources: StaticResources, emitCallback: EmitCallback): Promise<string[]>
+  emit(contentDir: string, cfg: GlobalConfiguration, content: ProcessedContent[], resources: StaticResources, emitCallback: EmitCallback): Promise<FilePath[]>
   getQuartzComponents(): QuartzComponent[]
 }
 
 export interface EmitOptions {
-  slug: string
+  slug: ServerSlug
   ext: `.${string}` | ""
   content: string
 }
 
-export type EmitCallback = (data: EmitOptions) => Promise<string>
+export type EmitCallback = (data: EmitOptions) => Promise<FilePath>