# dotnet/docfx architecture

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

- Interactive diagram: https://gitdiagram.com/dotnet/docfx
- Repository: https://github.com/dotnet/docfx

## Overview

##### Project type and purpose
- This is a **CLI-driven static documentation site generator** built in .NET.
- It reads a JSON/YAML config, loads source files (Markdown, .NET XML comments, Swagger), processes them through multiple build steps, applies customizable templates (JavaScript/CSS), and outputs HTML, PDF, JSON, etc. It can also serve content locally via an embedded HTTP server.

##### High-level components
A. **CLI Frontend (“docfx”)**
– Entrypoint (Program.cs)
– Commands: Init, Build, Metadata, Merge, Serve, PDF, etc.
– Loads .NET configuration models (DocfxConfig, BuildJsonConfig).
– Invokes the build pipeline via `RunBuild`, `RunMetadata`, `RunMerge`, `RunServe`.
B. **Composition & Plugin Container**
– `CompositionContainer` loads implementations of `IDocumentProcessor`, `IDocumentBuildStep`, `IPostProcessor`, `ITemplatePreprocessor`, etc.
– Enables pluggable build steps (Conceptual, API, RestApi, SchemaDriven, UniversalReference, OverwriteDocuments, etc.).
C. **File Abstraction Layer**
– `FileAbstractLayer` & implementations (LocalFileReader/Writer, ManifestFileReader/Writer)
– Isolates how input files are read/written and how manifest and incremental build data are managed.
D. **Core Build Engine**
– `DocumentBuilder` orchestrates pipeline phases: Compile, Link, Template, Post-processing.
– Each “phase” uses handlers (CompilePhaseHandler, LinkPhaseHandler, etc.).
E. **Document Processors**
– **Conceptual**: markdown reader, ValidateConceptualDocumentMetadata -> outputs HTML/content model.
– **ManagedReference (.NET API)**: Roslyn-based metadata extraction, MREF processors, generates API reference pages.
– **RestApi**: Swagger JSON parser -> operation/tag splitting -> produces REST API docs.
– **SchemaDriven**: JSON schema validation and fragment merging.
– **UniversalReference**: merges multi-language API references into unified pages.
F. **Template Engine**
– Uses Mustache (via `MustacheTemplateRenderer`) or custom JS extensions.
– Template folders under `templates/` (default, modern, statictoc) contain HTML/JS/CSS partials and bundling scripts (NodeJS).
– Preprocessors (Jint/JavaScript) apply transformations (e.g., embedding code snippets, tab groups).
G. **Post-processors**
– e.g., `ExtractSearchIndex`, `SitemapGenerator`, `RemoveDebugInfo`, `ValidateBookmark`
– Operate on generated HTML/JSON before final output.
H. **Output & Serve**
– Writes to disk: HTML, JSON, PDF (via PdfBuilder using PDFPig), XRef maps.
– Embedded HTTP server (`RunServe`) serves the `_site` folder locally.

##### Relationships & Data Flow
1. **User CLI** → parses command → loads config
2. Config → CompositionContainer → instantiate processors & steps
3. **FileAbstractLayer** reads source files + manifest (for incremental builds)
4. **DocumentBuilder** executes phases in order:
- Metadata extraction (Roslyn, Swagger parser)
- Content compilation (markdown → AST → HTML parts)
- Linking (resolve XRef, URLs)
- Templating (apply HTML templates + partials + CSS/JS)
- Post­processing (search index, sitemap)
5. **Template build** (NodeJS) happens at build­time for the front­end assets in `templates/`
6. Final assets → disk
7. If `--serve`, embedded HTTP host serves those files on localhost:8080

##### Architectural patterns & design principles
- **Pipeline**: clear build phases (Compile, Link, Template, Post)
- **Plugin/DI**: extension points via `IDocumentProcessor`, `IDocumentBuildStep`, `ITemplatePreprocessor`, loaded by `CompositionContainer`
- **Separation of concerns**:
– File I/O (FileAbstractLayer) vs. Build Logic (DocumentBuilder) vs. Rendering (TemplateEngine)
– Data models (DataContracts.Common, RestApi, UniversalReference) separated from processing logic
- **Modular subprojects** each implement one area of functionality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Orchestration
    subgraph "CLI & Orchestration"
        CLI["docfx CLI (Program.cs)"]:::dotnet
        Models["Commands Models"]:::dotnet
        Extensions["ArrayOptionConverter"]:::dotnet
        Csproj["docfx.csproj"]:::dotnet
    end

    %% Composition & Plugin Container
    subgraph "Composition & Plugin Container"
        Composition["CompositionContainer"]:::dotnet
        Plugins["Docfx.Plugins Interfaces"]:::dotnet
        DocType["DocumentType Enum"]:::dotnet
    end

    %% File Abstract Layer
    subgraph "File Abstract Layer"
        FAL["FileAbstractLayer"]:::dotnet
        RealReader["RealFileReader/Writer"]:::dotnet
        ManifestIO["ManifestFileReader/Writer"]:::dotnet
        DefaultFAL["DefaultFileAbstractLayer"]:::dotnet
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        Builder["DocumentBuilder"]:::dotnet
        subgraph "Phases"
            Meta["Metadata Extraction"]:::dotnet
            Compile["Content Compilation"]:::dotnet
            Link["Linking"]:::dotnet
            TemplatePhase["Templating"]:::dotnet
            Post["Post‐processing"]:::dotnet
        end
    end

    %% Document Processors
    subgraph "Document Processors"
        Conceptual["Conceptual Processor"]:::dotnet
        ManagedRef["ManagedReference Processor"]:::dotnet
        RestApi["RestApi Processor"]:::dotnet
        Schema["SchemaDriven Processor"]:::dotnet
        Universal["UniversalReference Processor"]:::dotnet
        Overwrite["OverwriteDocuments Plugin"]:::dotnet
        OpLevel["OperationLevelRestApi"]:::dotnet
        TagLevel["TagLevelRestApi"]:::dotnet
    end

    %% Template Engine & Preprocessors
    subgraph "Template Engine"
        Mustache["MustacheTemplateRenderer"]:::dotnet
        JintPre["TemplateJintPreprocessor"]:::dotnet
        Preloader["PreprocessorLoader"]:::dotnet
        Templates["templates/"]:::js
    end

    %% Post-processors
    subgraph "Post-processors"
        SearchIdx["ExtractSearchIndex"]:::dotnet
        Sitemap["SitemapGenerator"]:::dotnet
        RemoveDebug["RemoveDebugInfo"]:::dotnet
        ValidateBM["ValidateBookmark"]:::dotnet
    end

    %% Output & Serve
    subgraph "Output & Serve"
        PDF["PdfBuilder"]:::external
        Serve["RunServe HTTP Server"]:::dotnet
        Outputs["_site Output"]:::external
    end

    %% NodeJS Assets Build
    NodeJS["Template Assets Build (NodeJS)"]:::external

    %% Relationships & Data Flow
    CLI -->|parses command| Models
    CLI -->|uses| Extensions
    CLI -->|project| Csproj
    CLI -->|loads config| Composition
    Composition -->|instantiates| Conceptual
    Composition -->|instantiates| ManagedRef
    Composition -->|instantiates| RestApi
    Composition -->|instantiates| Schema
    Composition -->|instantiates| Universal
    Composition -->|instantiates| Overwrite
    Composition -->|instantiates| OpLevel
    Composition -->|instantiates| TagLevel
    CLI -->|calls| Builder
    Builder -->|uses| FAL
    FAL -->|reads/writes| RealReader
    FAL -->|manifests| ManifestIO
    FAL -->|default| DefaultFAL
    Builder --> Meta
    Builder --> Compile
    Builder --> Link
    Builder --> TemplatePhase
    Builder --> Post
    Meta -->|Roslyn metadata| ManagedRef
    Meta -->|Swagger JSON| RestApi
    Compile -->|Markdown AST| Conceptual
    Link -->|resolve XRef| Universal
    TemplatePhase --> Mustache
    TemplatePhase --> JintPre
    TemplatePhase --> Preloader
    TemplatePhase --> Templates
    NodeJS --> Templates
    Post --> SearchIdx
    Post --> Sitemap
    Post --> RemoveDebug
    Post --> ValidateBM
    Post --> Outputs
    PDF --> Outputs
    Serve --> Outputs

    %% Click Events
    click CLI "https://github.com/dotnet/docfx/blob/main/src/docfx/Program.cs"
    click Models "https://github.com/dotnet/docfx/tree/main/src/docfx/Models"
    click Extensions "https://github.com/dotnet/docfx/blob/main/src/docfx/Extensions/ArrayOptionConverter.cs"
    click Csproj "https://github.com/dotnet/docfx/blob/main/src/docfx/docfx.csproj"
    click Composition "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/CompositionContainer.cs"
    click Plugins "https://github.com/dotnet/docfx/blob/main/src/Docfx.Plugins"
    click DocType "https://github.com/dotnet/docfx/blob/main/src/Docfx.Plugins/DocumentType.cs"
    click FAL "https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/FileAbstractLayer/FileAbstractLayer.cs"
    click RealReader "https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/FileAbstractLayer/RealFileReader.cs"
    click RealReader "https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/FileAbstractLayer/RealFileWriter.cs"
    click ManifestIO "https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/FileAbstractLayer/ManifestFileReader.cs"
    click ManifestIO "https://github.com/dotnet/docfx/blob/main/src/Docfx.Common/FileAbstractLayer/ManifestFileWriter.cs"
    click DefaultFAL "https://github.com/dotnet/docfx/blob/main/src/Docfx.Plugins/DefaultFileAbstractLayer.cs"
    click Builder "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/DocumentBuilder.cs"
    click Compile "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/CompilePhaseHandler.cs"
    click Link "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/LinkPhaseHandler.cs"
    click Post "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/PostProcessors/PostProcessorsManager.cs"
    click TemplatePhase "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/TemplateProcessors/TemplateProcessor.cs"
    click Conceptual "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/Conceptual/ConceptualDocumentProcessor.cs"
    click ManagedRef "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.ManagedReference/ManagedReferenceDocumentProcessor.cs"
    click RestApi "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.RestApi/RestApiDocumentProcessor.cs"
    click Schema "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.SchemaDriven/SchemaDrivenDocumentProcessor.cs"
    click Universal "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.UniversalReference/UniversalReferenceDocumentProcessor.cs"
    click Overwrite "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.OverwriteDocuments/MarkdownFragmentsCreator.cs"
    click OpLevel "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.OperationLevelRestApi/SplitRestApiToOperationLevel.cs"
    click TagLevel "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build.TagLevelRestApi/SplitRestApiToTagLevel.cs"
    click Mustache "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/TemplateProcessors/ViewRenderers/MustacheTemplateRenderer.cs"
    click JintPre "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/TemplateProcessors/Preprocessors/TemplateJintPreprocessor.cs"
    click Preloader "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/TemplateProcessors/Preprocessors/PreprocessorLoader.cs"
    click Templates "https://github.com/dotnet/docfx/tree/main/templates/"
    click SearchIdx "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/PostProcessors/ExtractSearchIndex.cs"
    click Sitemap "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/PostProcessors/SitemapGenerator.cs"
    click RemoveDebug "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/PostProcessors/RemoveDebugInfo.cs"
    click ValidateBM "https://github.com/dotnet/docfx/blob/main/src/Docfx.Build/PostProcessors/ValidateBookmark.cs"
    click PDF "https://github.com/dotnet/docfx/blob/main/src/Docfx.App/PdfBuilder.cs"
    click Serve "https://github.com/dotnet/docfx/blob/main/src/Docfx.App/RunServe.cs"

    %% Styles
    classDef dotnet fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef js fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100;
```
