How dotnet/docfx works
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)
• Postprocessing (search index, sitemap)
5. Template build (NodeJS) happens at buildtime for the frontend 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