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!,