quartz-research-note/content/advanced/paths.md

title
Paths in Quartz

Paths are pretty complex to reason about because, especially for a static site generator, they can come from so many places.

The current browser URL? Technically a path. A full file path to a piece of content? Also a path. What about a slug for a piece of content? Yet another path.

It would be silly to type these all as string and call it a day as it's pretty common to accidentally mistake one type of path for another. Unfortunately, TypeScript does not have nominal types for type aliases meaning even if you made custom types of a server-side slug or a client-slug slug, you can still accidentally assign one to another and TypeScript wouldn't catch it.

Luckily, we can mimic nominal typing using brands.

// instead of 
type ClientSlug = string

// we do
type ClientSlug = string & { __brand: "client" }

// that way, the following will fail typechecking
const slug: ClientSlug = "some random slug"

While this prevents most typing mistakes within our nominal typing system (e.g. mistaking a server slug for a client slug), it doesn't prevent us from accidentally mistaking a string for a client slug when we forcibly cast it.

Thus, we still need to be careful when casting from a string to one of these nominal types in the 'entrypoints', illustrated with hexagon shapes in the diagram below.

The following diagram draws the relationships between all the path sources, nominal path types, and what functions in quartz/path.ts convert between them.

graph LR
    Browser{{Browser}} --> Window{{Window}} & LinkElement{{Link Element}}
    Window --"getCanonicalSlug()"--> Canonical[Canonical Slug]
    Window --"getClientSlug()"--> Client[Client Slug]
    LinkElement --".href"--> Relative[Relative URL]
    Client --"canonicalizeClient()"--> Canonical
    Canonical --"pathToRoot()"--> Relative
    Canonical --"resolveRelative()" --> Relative
    MD{{Markdown File}} --> FilePath{{File Path}} & Links[Markdown links]
    Links --"transformLink()"--> Relative
    FilePath --"slugifyFilePath()"--> Server[Server Slug]
    Server --> HTML["HTML File"]
    Server --"canonicalizeServer()"--> Canonical
    style Canonical stroke-width:4px