From 527ce6546e7ec50e7720ff7b9b6ff79a89c3b7fc Mon Sep 17 00:00:00 2001
From: Jacky Zhao <j.zhao2k19@gmail.com>
Date: Tue, 08 Aug 2023 04:41:18 +0000
Subject: [PATCH] various css fixes, fix new image loading bug when previewing, path docs
---
content/advanced/paths.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 45 insertions(+), 0 deletions(-)
diff --git a/content/advanced/paths.md b/content/advanced/paths.md
index e69de29..2a5e09f 100644
--- a/content/advanced/paths.md
+++ b/content/advanced/paths.md
@@ -0,0 +1,45 @@
+---
+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](https://en.wikipedia.org/wiki/Nominal_type_system) 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](https://www.typescriptlang.org/play#example/nominal-typing).
+
+```typescript
+// 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.
+
+```mermaid
+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
+```
--
Gitblit v1.10.0