# kazuyanagimoto/quarto-clean-typst architecture

> Architecture diagram of the GitHub repository kazuyanagimoto/quarto-clean-typst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kazuyanagimoto/quarto-clean-typst
- Repository: https://github.com/kazuyanagimoto/quarto-clean-typst

## Overview

##### Project Type & Purpose
- This is an **open-source Quarto extension/template** (“quarto-clean-typst”) that provides a minimalistic presentation theme based on Typst.
- It plugs into the Quarto CLI and relies on Typst (with Touying libraries) to render PDF/HTML slides.

##### High-level Components
a. **User / Author**
- Writes `.qmd` files (slides) using the provided template.
b. **Quarto CLI**
- Core engine that discovers extensions under `_extensions/clean`.
- Drives the rendering pipeline (Markdown/Typst → PDF/HTML).
c. **Extension Layer** (`_extensions/clean`)
- `extension.yml` – declares the theme and filters.
- `revealjs.lua` / `shortcodes.lua` – Lua filters for Quarto.
- `typst-environment.lua` / `.typ` templates – glue Typst code into Quarto.
- `typst-show.typ` & `typst-template.typ` – Typst theme definitions.
d. **Static Assets** (`static/img`, `static/references.bib`)
- Logos, thumbnails, bibliography files.
e. **Template Files** (`template*.qmd`, `touying-quarto-clean/template/main.typ`)
- Starter `.qmd` documents and Typst source for the bundled template.
f. **Custom Typst Configuration** (`custom.typ`, `typst.toml`)
- User-centric Typst overrides and project settings.
g. **Dependency & Environment Management**
- `renv/` & `renv.lock` – R package ecosystem lockfile.
- `air.toml` – task runner config.
- `Justfile` – shortcut commands for build/test/publish.
h. **CI / CD** (`.github/workflows`)
- `publish.yml` – automates release packaging.
- `typst-release.yml` – publishes Typst artifacts.

##### Interactions & Data Flow
1. **Development Flow**
- Dev runs `just setup` → installs Quarto extension, Typst libs, R packages (`renv activate`).
- Dev writes/edits theme files, runs `just build` or `quarto preview` to test.
2. **Rendering Flow (End-user)**
- User installs via `quarto install extension kazuyanagimoto/quarto-clean-typst`.
- Quarto CLI loads `_extensions/clean` and applies Lua filters + Typst templates.
- Quarto invokes Typst compiler (with Touying) to produce final PDF/HTML.
3. **Release Flow**
- GitHub Actions trigger on push/tag → run tests, build theme, publish to Quarto registry and GitHub Releases.

##### Architectural Patterns & Principles
- **Plugin Architecture**: Quarto discovers and loads extensions under `_extensions`.
- **Separation of Concerns**:
– Typst code (`*.typ`) separate from Quarto filters (`*.lua`).
– Static assets in `static/`.
– Templates in root vs. nested repo copy (`touying-quarto-clean/`).
- **Infrastructure as Code**: CI workflows and `Justfile` automate build & release.

[ ] Main components clearly labeled (User, Quarto CLI, Extension, Typst Compiler, Static Assets, CI/CD)
- how Quarto discovers and loads the extension
- how Lua filters and Typst templates are invoked
- how output artifacts (PDF, HTML) are generated
- how CI workflows publish to the Quarto registry and GitHub
[ ] Grouped modules (Developer Tooling vs. Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    User["User / Author"]:::external
    click User "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/template.qmd"

    %% Runtime System
    subgraph "Runtime Flow" 
        direction TB
        CLI["Quarto CLI"]:::internal
        click CLI "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_quarto.yml"

        subgraph "Quarto Extension" 
            direction TB
            ExtYML["extension.yml"]:::internal
            click ExtYML "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/_extension.yml"
            Reveal["revealjs.lua"]:::internal
            click Reveal "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/revealjs.lua"
            Shortcodes["shortcodes.lua"]:::internal
            click Shortcodes "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/shortcodes.lua"
            EnvLua["typst-environment.lua"]:::internal
            click EnvLua "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/typst-environment.lua"
            TypstShow["typst-show.typ"]:::internal
            click TypstShow "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/typst-show.typ"
            TypstTemplate["typst-template.typ"]:::internal
            click TypstTemplate "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/_extensions/clean/typst-template.typ"
        end

        subgraph "Typst Toolchain"
            direction TB
            TypstComp["Typst Compiler"]:::internal
            Touying["Touying Library"]:::internal
            click Touying "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/touying-quarto-clean/lib.typ"
        end

        subgraph "Assets & Templates"
            direction TB
            StaticAssets["Static Assets"]:::data
            click StaticAssets "https://github.com/kazuyanagimoto/quarto-clean-typst/tree/main/static/img/"
            click StaticAssets "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/static/references.bib"
            BundledTemplate["Bundled Template"]:::internal
            click BundledTemplate "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/touying-quarto-clean/template/main.typ"
            click BundledTemplate "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/touying-quarto-clean/typst.toml"
            click BundledTemplate "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/touying-quarto-clean/README.md"
            click BundledTemplate "https://github.com/kazuyanagimoto/quarto-clean-typst/tree/main/touying-quarto-clean/LICENSE"
            CustomConfig["Custom Typst Config"]:::internal
            click CustomConfig "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/custom.typ"
        end

        Output["PDF/HTML Slides"]:::output
    end

    %% Developer Tooling
    subgraph "Developer Tooling"
        direction TB
        Renv["renv/ & renv.lock"]:::data
        click Renv "https://github.com/kazuyanagimoto/quarto-clean-typst/tree/main/renv/"
        click Renv "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/renv.lock"
        Justfile["Justfile"]:::internal
        click Justfile "https://github.com/kazuyanagimoto/quarto-clean-typst/tree/main/Justfile"
        Air["air.toml"]:::internal
        click Air "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/air.toml"
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        PublishCI["publish.yml"]:::internal
        click PublishCI "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/.github/workflows/publish.yml"
        TypstReleaseCI["typst-release.yml"]:::internal
        click TypstReleaseCI "https://github.com/kazuyanagimoto/quarto-clean-typst/blob/main/.github/workflows/typst-release.yml"
        GitHub["GitHub Actions"]:::external
    end

    %% Flows
    User -->|"writes .qmd slides"| CLI
    CLI -->|"discover & load extension"| ExtYML
    CLI -->|"apply Lua filters"| Reveal
    CLI -->|"apply shortcodes"| Shortcodes
    Reveal -->|"inject Typst environment"| EnvLua
    EnvLua --> TypstShow
    EnvLua --> TypstTemplate
    CLI -->|"invoke Typst"| TypstComp
    TypstComp --> Touying
    TypstComp -->|"uses templates & assets"| BundledTemplate
    TypstComp -->|"uses assets"| StaticAssets
    CustomConfig -->|"overrides"| TypstComp
    TypstComp -->|"generate slides"| Output

    Justfile -->|"setup/build/test"| CLI
    Renv -->|"provides R env"| CLI

    GitHub --> PublishCI
    GitHub --> TypstReleaseCI
    PublishCI -->|"build & publish"| CLI
    TypstReleaseCI -->|"package Typst artifacts"| Touying

    %% Styles
    classDef external fill:#d2f8d2,stroke:#3a7;
    classDef internal fill:#d2e4ff,stroke:#357;
    classDef data fill:#ffe4e1,stroke:#d00;
    classDef output fill:#fafad2,stroke:#aa0;
```
