# rbmirc/essays architecture

> Architecture diagram of the GitHub repository rbmirc/essays, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rbmirc/essays
- Repository: https://github.com/rbmirc/essays

## Overview

This repository is a bilingual research-essay site built on Quartz, with private-group Hypothesis annotations documented as an optional collaboration feature. The principal workflow is Markdown ingestion, transformation and filtering, followed by static page generation and a reader-facing site with search, navigation, and language-aware presentation. The source index supports the build/parse/plugin and component relationships shown; unsampled Quartz capabilities are represented at subsystem level where their exact implementation paths are available. Hypothesis wiring is documented in the README, not verified in the sampled source.

Main entry points: [`quartz/processors/parse.ts`](https://github.com/rbmirc/essays/blob/main/quartz/processors/parse.ts) (Markdown parsing), [`quartz/build.ts`](https://github.com/rbmirc/essays/blob/main/quartz/build.ts) (Build orchestration), [`quartz.config.ts`](https://github.com/rbmirc/essays/blob/main/quartz.config.ts) (Site configuration), [`quartz/components/renderPage.tsx`](https://github.com/rbmirc/essays/blob/main/quartz/components/renderPage.tsx) (Published site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content processing"]
  node_parse["Markdown parsing<br/>[parse.ts]"]
  node_transformers["Content transformers"]
  node_filters["Publish filters"]
  node_vfile["Processed content<br/>[vfile.ts]"]
end

subgraph group_generation["Static generation"]
  node_build["Build orchestration<br/>[build.ts]"]
  node_emitters["Page and asset emitters"]
  node_config["Site configuration<br/>[quartz.config.ts]"]
  node_layout["Page layout<br/>[quartz.layout.ts]"]
end

subgraph group_experience["Reader experience"]
  node_site["Published site<br/>[renderPage.tsx]"]
  node_components["Page components<br/>[ArticleTitle.tsx]"]
  node_search["Search interface<br/>[Search.tsx]"]
  node_searchscript["Search behavior<br/>[search.inline.ts]"]
  node_pageviews["Tag and folder pages<br/>[TagContent.tsx]"]
  node_language["Locale translations<br/>[index.ts]"]
  node_date["Date display<br/>[Date.tsx]"]
  node_pagelist["Essay listings<br/>[PageList.tsx]"]
end

subgraph group_foundation["Shared foundations"]
  node_ctx["Build context<br/>[ctx.ts]"]
  node_paths["Slug and link paths<br/>[path.ts]"]
  node_resources["Page resources<br/>[resources.tsx]"]
  node_jsx["HTML to JSX<br/>[jsx.tsx]"]
  node_theme["Theme settings<br/>[theme.ts]"]
  node_logger["Build logging<br/>[log.ts]"]
  node_perf["Build timing<br/>[perf.ts]"]
  node_trace["Error tracing<br/>[trace.ts]"]
end

node_author(("Essay author"))
node_essays["Bilingual essays"]
node_visitor(("Site reader"))
node_hypothesis["Hypothesis service"]

node_author -->|"writes essays"| node_essays
node_essays -.->|"builds from"| node_build
node_build -->|"loads config"| node_config
node_build -->|"creates context"| node_ctx
node_build -->|"parses files"| node_parse
node_build -->|"filters content"| node_filters
node_build -->|"emits output"| node_emitters
node_parse -->|"applies plugins"| node_transformers
node_parse -->|"produces content"| node_vfile
node_parse -->|"uses context"| node_ctx
node_filters -->|"checks content"| node_vfile
node_emitters -->|"emits from content"| node_vfile
node_config -->|"configures plugins"| node_transformers
node_config -->|"configures layout"| node_layout
node_emitters -.->|"renders pages"| node_components
node_visitor -->|"reads"| node_site
node_site -->|"offers search"| node_search
node_search -->|"loads behavior"| node_searchscript
node_pageviews -->|"renders listings"| node_pagelist
node_pageviews -->|"converts content"| node_jsx
node_pagelist -->|"displays dates"| node_date
node_language -.->|"translates interface"| node_site
node_site -.->|"loads annotations"| node_hypothesis
node_ctx -->|"holds configuration"| node_config
node_ctx -->|"uses path types"| node_paths
node_resources -->|"types page data"| node_vfile
node_theme -->|"defines theme"| node_config
node_parse -->|"measures parsing"| node_perf
node_parse -->|"logs progress"| node_logger
node_parse -->|"traces failures"| node_trace

click node_parse "https://github.com/rbmirc/essays/blob/main/quartz/processors/parse.ts"
click node_transformers "https://github.com/rbmirc/essays/tree/main/quartz/plugins/transformers"
click node_filters "https://github.com/rbmirc/essays/tree/main/quartz/plugins/filters"
click node_vfile "https://github.com/rbmirc/essays/blob/main/quartz/plugins/vfile.ts"
click node_build "https://github.com/rbmirc/essays/blob/main/quartz/build.ts"
click node_emitters "https://github.com/rbmirc/essays/tree/main/quartz/plugins/emitters"
click node_config "https://github.com/rbmirc/essays/blob/main/quartz.config.ts"
click node_layout "https://github.com/rbmirc/essays/blob/main/quartz.layout.ts"
click node_site "https://github.com/rbmirc/essays/blob/main/quartz/components/renderPage.tsx"
click node_components "https://github.com/rbmirc/essays/blob/main/quartz/components/ArticleTitle.tsx"
click node_search "https://github.com/rbmirc/essays/blob/main/quartz/components/Search.tsx"
click node_searchscript "https://github.com/rbmirc/essays/blob/main/quartz/components/scripts/search.inline.ts"
click node_pageviews "https://github.com/rbmirc/essays/blob/main/quartz/components/pages/TagContent.tsx"
click node_language "https://github.com/rbmirc/essays/blob/main/quartz/i18n/index.ts"
click node_ctx "https://github.com/rbmirc/essays/blob/main/quartz/util/ctx.ts"
click node_paths "https://github.com/rbmirc/essays/blob/main/quartz/util/path.ts"
click node_resources "https://github.com/rbmirc/essays/blob/main/quartz/util/resources.tsx"
click node_jsx "https://github.com/rbmirc/essays/blob/main/quartz/util/jsx.tsx"
click node_date "https://github.com/rbmirc/essays/blob/main/quartz/components/Date.tsx"
click node_pagelist "https://github.com/rbmirc/essays/blob/main/quartz/components/PageList.tsx"
click node_theme "https://github.com/rbmirc/essays/blob/main/quartz/util/theme.ts"
click node_logger "https://github.com/rbmirc/essays/blob/main/quartz/util/log.ts"
click node_perf "https://github.com/rbmirc/essays/blob/main/quartz/util/perf.ts"
click node_trace "https://github.com/rbmirc/essays/blob/main/quartz/util/trace.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parse,node_transformers,node_filters,node_vfile toneBlue
class node_build,node_emitters,node_config,node_layout toneAmber
class node_site,node_components,node_search,node_searchscript,node_pageviews,node_language,node_date,node_pagelist toneMint
class node_ctx,node_paths,node_resources,node_jsx,node_theme,node_logger,node_perf,node_trace toneRose
class node_author,node_essays,node_visitor,node_hypothesis toneIndigo
```

## Components

### Content processing

- [Markdown parsing](https://github.com/rbmirc/essays/blob/main/quartz/processors/parse.ts): `quartz/processors/parse.ts`
- [Content transformers](https://github.com/rbmirc/essays/tree/main/quartz/plugins/transformers): `quartz/plugins/transformers`
- [Publish filters](https://github.com/rbmirc/essays/tree/main/quartz/plugins/filters): `quartz/plugins/filters`
- [Processed content](https://github.com/rbmirc/essays/blob/main/quartz/plugins/vfile.ts): `quartz/plugins/vfile.ts`

### Static generation

- [Build orchestration](https://github.com/rbmirc/essays/blob/main/quartz/build.ts): `quartz/build.ts`
- [Page and asset emitters](https://github.com/rbmirc/essays/tree/main/quartz/plugins/emitters): `quartz/plugins/emitters`
- [Site configuration](https://github.com/rbmirc/essays/blob/main/quartz.config.ts): `quartz.config.ts`
- [Page layout](https://github.com/rbmirc/essays/blob/main/quartz.layout.ts): `quartz.layout.ts`

### Reader experience

- [Published site](https://github.com/rbmirc/essays/blob/main/quartz/components/renderPage.tsx): `quartz/components/renderPage.tsx`
- [Page components](https://github.com/rbmirc/essays/blob/main/quartz/components/ArticleTitle.tsx): `quartz/components/ArticleTitle.tsx`
- [Search interface](https://github.com/rbmirc/essays/blob/main/quartz/components/Search.tsx): `quartz/components/Search.tsx`
- [Search behavior](https://github.com/rbmirc/essays/blob/main/quartz/components/scripts/search.inline.ts): `quartz/components/scripts/search.inline.ts`
- [Tag and folder pages](https://github.com/rbmirc/essays/blob/main/quartz/components/pages/TagContent.tsx): `quartz/components/pages/TagContent.tsx`
- [Locale translations](https://github.com/rbmirc/essays/blob/main/quartz/i18n/index.ts): `quartz/i18n/index.ts`
- [Date display](https://github.com/rbmirc/essays/blob/main/quartz/components/Date.tsx): `quartz/components/Date.tsx`
- [Essay listings](https://github.com/rbmirc/essays/blob/main/quartz/components/PageList.tsx): `quartz/components/PageList.tsx`

### Shared foundations

- [Build context](https://github.com/rbmirc/essays/blob/main/quartz/util/ctx.ts): `quartz/util/ctx.ts`
- [Slug and link paths](https://github.com/rbmirc/essays/blob/main/quartz/util/path.ts): `quartz/util/path.ts`
- [Page resources](https://github.com/rbmirc/essays/blob/main/quartz/util/resources.tsx): `quartz/util/resources.tsx`
- [HTML to JSX](https://github.com/rbmirc/essays/blob/main/quartz/util/jsx.tsx): `quartz/util/jsx.tsx`
- [Theme settings](https://github.com/rbmirc/essays/blob/main/quartz/util/theme.ts): `quartz/util/theme.ts`
- [Build logging](https://github.com/rbmirc/essays/blob/main/quartz/util/log.ts): `quartz/util/log.ts`
- [Build timing](https://github.com/rbmirc/essays/blob/main/quartz/util/perf.ts): `quartz/util/perf.ts`
- [Error tracing](https://github.com/rbmirc/essays/blob/main/quartz/util/trace.ts): `quartz/util/trace.ts`

### Other components

- **Essay author**
- **Bilingual essays**
- **Site reader**
- **Hypothesis service**

## Connections

- Essay author → Bilingual essays: writes essays (evidence: `README.md`)
- Bilingual essays → Build orchestration: builds from
- Build orchestration → Site configuration: loads config (evidence: `quartz/build.ts`)
- Build orchestration → Build context: creates context (evidence: `quartz/build.ts`)
- Build orchestration → Markdown parsing: parses files (evidence: `quartz/build.ts`)
- Build orchestration → Publish filters: filters content (evidence: `quartz/build.ts`)
- Build orchestration → Page and asset emitters: emits output (evidence: `quartz/build.ts`)
- Markdown parsing → Content transformers: applies plugins (evidence: `quartz/processors/parse.ts`)
- Markdown parsing → Processed content: produces content (evidence: `quartz/processors/parse.ts`)
- Markdown parsing → Build context: uses context (evidence: `quartz/processors/parse.ts`)
- Publish filters → Processed content: checks content
- Page and asset emitters → Processed content: emits from content
- Site configuration → Content transformers: configures plugins (evidence: `quartz.config.ts`)
- Site configuration → Page layout: configures layout (evidence: `quartz.layout.ts`)
- Page and asset emitters → Page components: renders pages
- Site reader → Published site: reads (evidence: `README.md`)
- Published site → Search interface: offers search
- Search interface → Search behavior: loads behavior (evidence: `quartz/components/Search.tsx`)
- Tag and folder pages → Essay listings: renders listings (evidence: `quartz/components/pages/TagContent.tsx`)
- Tag and folder pages → HTML to JSX: converts content (evidence: `quartz/components/pages/TagContent.tsx`)
- Essay listings → Date display: displays dates (evidence: `quartz/components/PageList.tsx`)
- Locale translations → Published site: translates interface
- Published site → Hypothesis service: loads annotations (evidence: `README.md`)
- Build context → Site configuration: holds configuration (evidence: `quartz/util/ctx.ts`)
- Build context → Slug and link paths: uses path types (evidence: `quartz/util/ctx.ts`)
- Page resources → Processed content: types page data (evidence: `quartz/util/resources.tsx`)
- Theme settings → Site configuration: defines theme
- Markdown parsing → Build timing: measures parsing (evidence: `quartz/processors/parse.ts`)
- Markdown parsing → Build logging: logs progress (evidence: `quartz/processors/parse.ts`)
- Markdown parsing → Error tracing: traces failures (evidence: `quartz/processors/parse.ts`)
