chakradharsai5/my-notes

Purpose and Entry Points

This repository is a Quartz v4 digital-garden site: it converts the owner’s Obsidian-compatible Markdown vault into a static website. The primary source of truth is content/; the root note is content/index.md. Build/runtime configuration enters through quartz.config.ts and layout composition through quartz.layout.ts. The CLI/bootstrap layer starts the build pipeline from quartz/bootstrap-cli.mjs and quartz/build.ts.

Content Domain and Boundaries

The repository is content-heavy rather than application-heavy. Markdown notes, attachments, Excalidraw artifacts, and PDFs are stored together under content/, including the main knowledge base at content/1 Knowledge Hub, journals at content/2 Time Capsule, and authoring templates/assets at content/Obsidian Functional Stuff.

Quartz treats this directory as untrusted author content: parsing, frontmatter interpretation, link resolution, filtering, and output emission occur in the framework boundary rather than in the notes themselves. Notes can use Obsidian conventions and internal links.

Build Orchestration

The build is a staged static-site generator:

1. discover and parse source files;

2. apply content transformers;

3. remove excluded/draft content through filters;

4. emit pages, indexes, assets, and supporting resources.

These stages are implemented by quartz/processors/parse.ts, quartz/processors/filter.ts, and quartz/processors/emit.ts, coordinated by quartz/build.ts. quartz/worker.ts and quartz/bootstrap-worker.mjs support worker-based execution, separating CLI process startup from build work.

Content Transformation and Graph Semantics

Transformers normalize Markdown into rendered content and metadata. Architecturally important transformations include frontmatter parsing, Obsidian-flavored Markdown/wikilinks, link crawling, descriptions, syntax highlighting, and table-of-contents generation. Their registrations and shared contracts live in quartz/plugins/transformers/index.ts and quartz/plugins/types.ts; examples include quartz/plugins/transformers/ofm.ts, quartz/plugins/transformers/links.ts, and quartz/plugins/transformers/frontmatter.ts.

Resolved links and content metadata drive backlinks, graph view, folder/tag listings, search indexing, aliases, and page routes.

Page Rendering and UI Composition

Quartz renders static HTML/JS/CSS using TypeScript and TSX components. Page-level rendering is centered on quartz/components/renderPage.tsx, with page variants in quartz/components/pages/Content.tsx, quartz/components/pages/FolderContent.tsx, and quartz/components/pages/TagContent.tsx. The configured layout selects reusable UI components such as navigation, search, backlinks, graph, and explorer from quartz/components/.

Client-side enhancements are isolated as inline scripts—for example quartz/components/scripts/search.inline.ts, quartz/components/scripts/graph.inline.ts, and quartz/components/scripts/spa.inline.ts—rather than requiring an application server.

Output Emission

Emitters materialize the processed content into static-site artifacts: per-note pages, folder/tag pages, content indexes/search data, aliases, static assets, resource bundles, 404 pages, and optional social images. Core emitters are under quartz/plugins/emitters/, especially contentPage.tsx, contentIndex.tsx, and componentResources.ts. This is the main boundary from internal Quartz FilePath/vfile representations to deployable files.

Runtime, Delivery, and External Services

The project runs on Node.js (version pinned by .node-version) with npm dependency management (package.json, package-lock.json) and TypeScript. It can be containerized through Dockerfile. GitHub Actions provides CI, previews, deployment, Docker image build/push, and synchronization workflows under .github/workflows/, including ci.yaml, deploy.yml, and deploy-preview.yaml. No database or backend API is represented; deployment serves generated static assets. A Giscus styling asset exists at quartz/static/giscus, indicating optional GitHub Discussions-based comments support.