# quarto-dev/quarto-web architecture

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

- Interactive diagram: https://gitdiagram.com/quarto-dev/quarto-web
- Repository: https://github.com/quarto-dev/quarto-web

## Overview

##### PROJECT TYPE & PURPOSE
- This repository is not a typical full-stack application; rather, it is the source and build configuration for the Quarto documentation website (“quarto.org”) with a pre-release counterpart (“prerelease.quarto.org”). The repository is designed to serve as both the content repository (with dozens of .qmd documents, blogs, tutorials, and example projects) and the build/infrastructure configuration. It integrates static site generation (via Quarto “render” commands), a freeze state for reproducible computational outputs (stored in the _freeze folder), and dependency management for both R (via renv) and Python (via pipenv).

##### FILE STRUCTURE ANALYSIS
- Key top-level folders include:
– docs: Contains the bulk of documentation content (blog posts, guides, examples, presentations, interactive demos, etc.).
– _freeze: Holds the frozen outputs for reproducible code execution.
– _extensions: Custom Quarto extensions that augment how documents are rendered.
– .github/workflows: Contains CI/CD pipeline definitions and various release and publishing scripts.
– renv, Pipfile/Pipfile.lock, and .env: Define the R and Python environments, respectively, which are necessary for processing documents that include computational outputs.
– tools: Various scripts for generating reference pages and handling other tasks.

##### ADDITIONAL INSIGHTS FROM THE README
- The README explains that “freeze: true” is used to avoid having to run live computations during a render; thus, the _freeze directory is essential in the build pipeline.
- It details separate instructions for setting up R (using renv) and Python (using pipenv) environments, thus emphasizing the layered dependency management.
- There’s an external dependency note for the Quarto CLI schema (for generating reference pages) that ties the docs to the main “quarto-cli” repository.

a. Main Components:
– Documentation Sources: The .qmd files, markdown documents, assets (images, videos) under docs/, blog, presentations, etc.
– Computation Freeze Mechanism: The _freeze folder that stores computed outputs determined by Quarto when ‘freeze’ is enabled.
– Build/Render Engine: The Quarto CLI that processes source files; this component interfaces with the custom extensions (_extensions).
– Environment Management:
◦ R Environment: Managed by renv (with DESCRIPTION, renv.lock, .Rprofile).
◦ Python Environment: Managed by pipenv (with Pipfile, Pipfile.lock, and .env configuration leading to a .venv).
– CI/CD Pipeline: GitHub Actions defined under .github/workflows to handle tasks such as previewing changes, versioning and publishing.
– External Systems:
◦ The upstream Quarto CLI repository (for reference schema generation).
◦ Hosting targets: The published websites (quarto.org and prerelease.quarto.org).

b. Relationships and Data Flow:
– The Documentation Sources are fed into the Build/Render Engine.
– The Render Engine uses both the R and Python environments (via renv and pipenv) to process computation (using knitr, Jupyter, or reticulate).
– Computation outputs are “frozen” into the _freeze folder which is then used on subsequent renders.
– Custom extensions (found in _extensions) plug into the render engine to enhance the output.
– The CI/CD pipeline (GitHub Actions) automates the build process, triggering renders and then publishing the static site.
– Tools scripts (in tools/) and external integrations (like quarto-cli/schema reference generation) interact with the render/build process.

c. Architectural Patterns and Design Principles:
– Separation of concerns: Source documents (content), build engine, dependencies, and publishing workflows are clearly separated.
– Immutable build artifacts: The freeze mechanism guarantees reproducible builds.
– Automated CI/CD: GitHub workflows ensure changes are automatically built and deployed.
– Environment isolation: Use of renv and pipenv encapsulates the respective environments, ensuring consistent dependency management.

d. Key Technologies:
– Quarto CLI for static site generation.
– R (with knitr and renv) and Python (via pipenv, Jupyter, and reticulate) for document computations.
– GitHub Actions for CI/CD.
– Custom Quarto extensions for enhancing document rendering.
– Supplementary libraries under _freeze/site_libs (e.g., for interactive elements, Reveal.js for presentations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Layer
    DocSource["Documentation Source"]:::content
    Tools["Tools & Scripts"]:::tool
    CICD["CI/CD Pipeline"]:::automation
    External["Quarto CLI Repo"]:::external

    %% Processing Layer
    QuartoEngine["Quarto Render Engine"]:::engine
    Extensions["Extensions"]:::engine

    %% Dependency Management - R Environment
    subgraph "R Environment"
        R1["renv"]:::dependency
        R2["DESCRIPTION"]:::dependency
        R3[".Rprofile"]:::dependency
    end

    %% Dependency Management - Python Environment
    subgraph "Python Environment"
        P1["Pipfile"]:::dependency
        P2["Pipfile.lock"]:::dependency
        P3[".env"]:::dependency
    end

    %% Build Artifacts
    Freeze["Freeze Mechanism"]:::cache
    Deployment["Deployment/Hosting"]:::deploy

    %% Flow connections
    DocSource -->|"feeds"| QuartoEngine
    Tools -->|"triggers"| QuartoEngine
    CICD -->|"automates"| QuartoEngine
    External -->|"supplies"| QuartoEngine
    Extensions -->|"integrates"| QuartoEngine

    R1 -->|"dependency"| QuartoEngine
    R2 -->|"dependency"| QuartoEngine
    R3 -->|"dependency"| QuartoEngine

    P1 -->|"dependency"| QuartoEngine
    P2 -->|"dependency"| QuartoEngine
    P3 -->|"dependency"| QuartoEngine

    QuartoEngine -->|"freezes output"| Freeze
    Freeze -->|"delivers"| Deployment

    %% Click Events
    click DocSource "https://github.com/quarto-dev/quarto-web/tree/main/docs/"
    click QuartoEngine "https://github.com/quarto-dev/quarto-web/blob/main/_quarto.yml"
    click Extensions "https://github.com/quarto-dev/quarto-web/tree/main/_extensions/"
    click CICD "https://github.com/quarto-dev/quarto-web/tree/main/.github/workflows/"
    click Tools "https://github.com/quarto-dev/quarto-web/tree/main/tools/"
    click R1 "https://github.com/quarto-dev/quarto-web/tree/main/renv/"
    click R2 "https://github.com/quarto-dev/quarto-web/tree/main/DESCRIPTION"
    click R3 "https://github.com/quarto-dev/quarto-web/blob/main/.Rprofile"
    click P1 "https://github.com/quarto-dev/quarto-web/tree/main/Pipfile"
    click P2 "https://github.com/quarto-dev/quarto-web/blob/main/Pipfile.lock"
    click P3 "https://github.com/quarto-dev/quarto-web/blob/main/.env"
    click Freeze "https://github.com/quarto-dev/quarto-web/tree/main/_freeze/"

    %% Class Definitions
    classDef content fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef engine fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef dependency fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef automation fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef tool fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef cache fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef deploy fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#004085,stroke-width:2px;
```
