Quartz

Overview (reference, docs)

Quartz is for publishing notebooks (like Obsidian notebooks) into a nice, web-based form.

Alternatives

• MkDocs with a theme like Material, e.g. Jumumu’s repo here (which even has an action to publish to the gh-pages branch of the repo (something that mkdocs gh-deploy knows about)) - see it live here
  • They even made a generic deploy action here.
• Starlight
  • From Jumumu on 01/27/2024:
    • https://jumumu.github.io/starlight-starter/
    • https://github.com/Jumumu/starlight-starter
    • Overall, there’s a bit more setup involved compared to MkDocs and I listed some gotcha’s at the top of the README.md. It’s also a bit less configurable out of the box, but it’s still nice. I think both are good options.

First use

I followed the instructions on the site (don’t try to use pnpm instead of npm since it doesn’t seem to work):

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

I chose these options:

┌   Quartz v4.1.4
│
◇  Choose how to initialize the content in `/Users/adam/tmp/quartz/content`
│  Copy an existing folder
│
◇  Enter the full path to existing content folder
│  /Volumes/inland/Documents/Obsidian\ Vaults/public
│
◇  Choose how Quartz should resolve links in your content. You can change this later in `quartz.config.ts`.
│  Treat links as shortest path

Then, before you can serve the files, create content/index.md with whatever you want in it (even just “hello world” for testing). It’ll serve as the first page that people see when they go to your notes. Ideally, index.md should just appear at the top level of your vault.

Finally, serve your files with npx quartz build --serve.

From here, you can modify your quartz.config.ts. Here’s my starter one:

```ts
import { QuartzConfig } from "./quartz/cfg"
import * as Plugin from "./quartz/plugins"

const config: QuartzConfig = {
  configuration: {
    pageTitle: "Adam Learns notes",
    enableSPA: true,
    enablePopovers: true,
    analytics: null,
    baseUrl: "notes.adamlearns.com",
    ignorePatterns: [
      "private",
      "templates",
      ".obsidian",
      "Development-Efficiency-Cheat-Sheets",
      "Adam-Learns---private",
      "Archived-garbage",
      "Language",
      "My-Notebook",
      "Infrequent",
      "Xtonomous-Knowledge",
      "Xtonomous",
    ],
    defaultDateType: "created",
    theme: {
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: {
          light: "#faf8f8",
          lightgray: "#e5e5e5",
          gray: "#b8b8b8",
          darkgray: "#4e4e4e",
          dark: "#2b2b2b",
          secondary: "#284b63",
          tertiary: "#84a59d",
          highlight: "rgba(143, 159, 169, 0.15)",
        },
        darkMode: {
          light: "#161618",
          lightgray: "#393639",
          gray: "#646464",
          darkgray: "#d4d4d4",
          dark: "#ebebec",
          secondary: "#c93379", // link color, current graph node
          tertiary: "#0A4DAA", // hover states and visited graph nodes
          highlight: "#84a59d", // internal link background, highlighted text/code
        },
      },
    },
  },
  plugins: {
    transformers: [
      Plugin.FrontMatter(),
      Plugin.TableOfContents(),
      Plugin.CreatedModifiedDate({
        priority: ["frontmatter", "filesystem"], // you can add 'git' here for last modified from Git but this makes the build slower
      }),
      Plugin.Latex({ renderEngine: "katex" }),
      Plugin.SyntaxHighlighting(),
      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
      Plugin.GitHubFlavoredMarkdown(),
      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
      Plugin.Description(),
    ],
    filters: [Plugin.RemoveDrafts()],
    emitters: [
      Plugin.AliasRedirects(),
      Plugin.ComponentResources({ fontOrigin: "googleFonts" }),
      Plugin.ContentPage(),
      Plugin.FolderPage(),
      Plugin.TagPage(),
      Plugin.ContentIndex({
        enableSiteMap: true,
        enableRSS: true,
      }),
      Plugin.Assets(),
      Plugin.Static(),
      Plugin.NotFoundPage(),
    ],
  },
}

export default config
```

Manually publishing to GitHub Pages

For automatically doing this, see this page.

Manually doing this is very quick! ⚡️

• Make your GitHub Pages repo following these instructions (it’s incredibly simple/fast, <30 seconds).
• Clone it somewhere
• Copy my public notes to Quartz’s content folder
  • Note: I actually just use a symlink: ln -s ./public /path/to/quartz/content
• Run the build: npx quartz build
• Copy the entirety of the public folder to the Pages repo (so that index.html is at a the top level): cp -r public/ OTHER_REPO

:::note]

• Don’t forget the trailing slash on public or you’ll end up with OTHER_REPO/public instead of OTHER_REPO/index.html!

:::

• Push
  • cd OTHER_REPO
  • Make sure you didn’t add any private notes/folders
  • git commit -am "Publish notes"
  • git push

Then, to get a custom domain, I went through cPanel:

• Delete the redirect that I had to OneNote
• Go to the Zone Editor
• Add a CNAME record pointing notes.adamlearns.com → adamlearns.github.io