Zhu Yuechen's Tech Notes

Site Workflow

Created Updated 4 min read

Reference for adding and maintaining content on this site.

Adding a new note

  1. Create the file in the right folder (see folder structure below)
  2. Add frontmatter:
---
title: Note Title
date: YYYY-MM-DD       # created — never change
lastmod: YYYY-MM-DD    # last meaningful edit — bump when adding content, not for typos
tags:
  - <folder-tag>    # e.g. go, infra, databases
  - <topic-tag>     # e.g. redis, kubernetes, protobuf
  - beep            # if work-specific
  - incident        # if it came from debugging a real issue
---
  1. Write the note — concise, no filler, code examples where useful
  2. Use callouts for gotchas, warnings, and key rules (see Callouts below)
  3. Add Mermaid diagrams for data flows or multi-step architectures (see Diagrams below)
  4. Add a ## See also section linking to related notes: [[note-filename]]
  5. Commit: git add content/ && git commit -m "feat: add note on <topic>"

See tagging-convention for the full tag reference.

Callouts

Use Obsidian-style callouts to highlight important information:

> [!warning]
> 
> **Title** — Something that will bite you if ignored.
 
> [!tip]
> 
> **Title** — A key rule or best practice.
 
> [!note]
> 
> Additional context worth flagging.

The inline title (> [!warning] Title) replaces the “Warning” header entirely. Put the title as bold text in the body to show both the type and the label.

When to use each:

  • [!warning] — “don’t do this”, silent failure modes, production gotchas
  • [!tip] — key rules, takeaways, rules of thumb
  • [!note] — context that isn’t obvious but isn’t a warning

Diagrams

Use Mermaid for flows and architectures that ASCII can’t express cleanly:

```mermaid
flowchart TD
    A[Input] --> B[Step]
    B --> C[(Database)]
```

Good candidates: request flows, before/after comparisons, multi-service interactions. Don’t add a diagram if the text already explains it clearly.

Mermaid gotchas:

  • Use <br/> for line breaks in node labels, not \n — \n renders as literal text
  • Wrap labels containing special characters or <br/> in double quotes: ["Label<br/>line 2"]
  • Edge labels with special characters also need quotes: -->|"label text"|

Adding a new folder

  1. Create the folder under content/
  2. Add a folder-level tag to tagging-convention if it’s a new top-level section
  3. Update the content/index.md if you want the section surfaced on the home page
  4. Notes inside should include the new folder tag

Editing an existing note

  • Edit the file directly
  • Bump lastmod: if you’re adding content (not for typo fixes)
  • Leave date: alone — it’s the creation date
  • Update ## See also links if the note now relates to something new
  • Commit: git add content/ && git commit -m "chore: update <note-name>"

Folder structure

content/
  auth/             → OpenFGA, JWT, IAM
  databases/
    mongodb/        → schema, Mongoose
    redis/          → caching, locks, pubsub
  design/           → architecture patterns
  devops/           → CI/CD, deployment pipelines
  distributed_systems/ → concurrency, coordination
  go/
    protobuf/       → .proto, codegen, Buf
  infra/
    docker/         → containers, networking, mounts
    kubernetes/     → K8s, k9s, kubectl
    observability/  → Grafana, Jaeger
    rabbitmq/       → queues, consumers, DLQ
  networking/       → DNS, TCP, ICMP, VPN
  nodejs/           → Express, Zod, middleware

Tracking open questions

Tag any note open when something is still unclear or worth investigating further:

tags:
  - go
  - open    # ← still have questions about this

All open notes appear automatically at open — your active learning queue. Remove the tag once resolved.

Weekly review

Every Monday a GitHub Actions workflow emails 5 notes to review, weighted toward notes you haven’t touched recently. To trigger manually: Actions → Weekly review → Run workflow.

Pulling Quartz framework updates

This site is built on Quartz v4. The upstream remote is already configured. To pull in framework updates:

git fetch upstream
git merge upstream/v4

What will conflict: quartz.config.ts and quartz.layout.ts if Quartz changes their structure. Resolve by keeping your values (baseUrl, footer links, layout components) and accepting Quartz’s structural changes.

What won’t conflict: everything in content/, scripts/, .githooks/ — Quartz never touches those.

Deployment

Push to v4 branch → Cloudflare Pages auto-deploys to yuechen-tech-notes.pages.dev.

git push

First-time setup (new machine)

# Activate the pre-commit health check
git config core.hooksPath .githooks
 
# Re-add the Quartz upstream remote
git remote add upstream https://github.com/jackyzha0/quartz

Graph View