If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dotnet/docfx shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 3 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 80% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dotnet/docfx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dotnet/docfx.

What it runs against: a local clone of dotnet/docfx — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dotnet/docfx | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dotnet/docfx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dotnet/docfx.git
#   cd docfx
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dotnet/docfx and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dotnet/docfx(\\.git)?\\b" \\
  && ok "origin remote is dotnet/docfx" \\
  || miss "origin remote is not dotnet/docfx (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "Directory.Packages.props" \\
  && ok "Directory.Packages.props" \\
  || miss "missing critical file: Directory.Packages.props"
test -f "docfx.slnx" \\
  && ok "docfx.slnx" \\
  || miss "missing critical file: docfx.slnx"
test -f "docs/docfx.json" \\
  && ok "docs/docfx.json" \\
  || miss "missing critical file: docs/docfx.json"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dotnet/docfx"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

DocFX is a static site generator that transforms .NET API documentation (from XML comments and YAML metadata) into a complete HTML documentation site with landing pages, markdown support, and cross-references. It consumes .NET reflection data and Markdown to generate SEO-friendly, searchable documentation sites deployable anywhere—used heavily by .NET teams to publish API docs similar to Microsoft Learn. Modular monorepo: core C# engine in src/ processes metadata and generates artifacts; separate TypeScript/JavaScript template build system in templates/ (npm-driven); documentation and examples in docs/. .NET solution structure uses Directory.Build.props for centralized package versioning; site generation pipeline chains multiple document processors (reflection → YAML → Markdown → HTML rendering).

.NET library authors and documentation teams who need to auto-generate API reference sites from source code comments; DevOps engineers deploying docs to Azure DevOps or static hosts; technical writers maintaining large .NET documentation projects with version control and CI/CD integration.

Mature and actively maintained as a .NET Foundation community project since Microsoft Learn transitioned it in Nov 2022. Production-ready with comprehensive CI/CD (.github/workflows/ci.yml, nightly builds), extensive test coverage, and regular releases to NuGet. Actively developed with nightly GitHub Packages builds available; community contributions are encouraged via help-wanted labels.

Low risk for core functionality but moderate risk for cutting-edge features: project transitioned from Microsoft stewardship to community-driven model, so feature velocity has slowed. Dependency surface is manageable (centralized in Directory.Packages.props), but the project spans multiple languages (C#, TypeScript, XSLT, Go templates) increasing maintenance complexity. Open issue backlog exists but no public burndown data visible; no obvious single-maintainer bottleneck evident.

Active development tracked via GitHub workflows: CI runs on every commit (ci.yml), nightly snapshot builds publish to GitHub Packages, dependabot manages dependency updates, and release automation is in place (release.yml). Recent focus appears to be on template modernization (TypeScript codebase) and stability as a community project—specific PRs/issues not visible in file list but help-wanted labels indicate ongoing contribution needs.

git clone https://github.com/dotnet/docfx.git
cd docfx
cd templates && npm install && npm run build && cd ..
dotnet build docfx.sln
dotnet test

Daily commands:

dotnet tool install -g docfx
dotnet build
dotnet run -- build docs/docfx.json --serve
# Visit https://localhost:8080

• Directory.Build.props — Central MSBuild properties file controlling project configuration, versioning, and dependencies across the entire solution.
• Directory.Packages.props — Centralized NuGet package version management for all projects, critical for dependency consistency.
• docfx.slnx — Main solution file that orchestrates all projects and build configuration for the docfx toolchain.
• docs/docfx.json — Primary configuration schema demonstrating docfx's own documentation build, serves as reference implementation.
• .github/workflows/ci.yml — Continuous integration pipeline defining build, test, and validation steps that all contributors must pass.
• CONTRIBUTING.md — Developer guidelines and contribution workflows that all new contributors must read before starting.
• README.md — Project overview explaining docfx's purpose as a static site generator for .NET API documentation and current community status.

• Metadata Extractor (.NET Reflection, YAML serial) — Reflects on .NET assemblies and generates YAML metadata containing types, members, signatures, and documentation

Add a Custom Document Processor

1. Review the RTF processor example to understand the IDocumentProcessor interface and lifecycle (docs/codesnippet/Rtf/RtfDocumentProcessor.cs)
2. Implement your processor following the metadata format specification (docs/spec/metadata_format_spec.md)
3. Register processor as a build step in your docfx.json configuration (docs/reference/docfx-json-reference.md)
4. Test your processor with the docfx build command (docs/reference/docfx-cli-reference/docfx-build.md)

Create a Custom Theme/Template

1. Read the template authoring guide and understand the template engine architecture (docs/docs/template.md)
2. Study existing community templates for structure and conventions (docs/extensions/templates.yml)
3. Configure your template in docfx.json template section (docs/reference/docfx-json-reference.md)
4. Use docfx build to generate output and validate theme rendering (docs/reference/docfx-cli-reference/docfx-build.md)

Configure Documentation for .NET APIs

1. Prepare assembly files and configure docfx.json metadata section (docs/docs/dotnet-api-docs.md)
2. Run docfx metadata to extract API documentation (docs/reference/docfx-cli-reference/docfx-metadata.md)
3. Create markdown overrides and document structure using TOC files (docs/docs/table-of-contents.md)
4. Build final documentation with docfx build (docs/reference/docfx-cli-reference/docfx-build.md)

Add Cross-References and Links

1. Understand docfx link syntax and cross-reference resolution (docs/docs/links-and-cross-references.md)
2. Configure xrefmap.json for external reference mapping (.xrefmap.json)
3. Use references in markdown and YAML documentation (docs/docs/markdown.md)

• .NET/C# — Enables direct reflection on .NET assemblies for API metadata extraction and positions docfx as native tooling for .NET developers
• YAML metadata format — Provides structured, version-controllable representation of API documentation that can be processed, merged, and customized independently of rendering
• Markdown + DocFX flavors — Combines familiar markdown syntax with docfx-specific extensions (xref, includes, notes) to enable rich documentation without requiring custom markup
• Liquid/Scriban templating — Allows separation of content from presentation, enabling multiple themes and customizable output without modifying core generation logic
• Static site generation — Produces serverless, CDN-friendly HTML output suitable for hosting on GitHub Pages, Azure Static Web Apps, or any web server

• Community-driven project post-Microsoft transition (Nov 2022)

  • Why: Microsoft Learn no longer uses docfx and cannot provide enterprise support
  • Consequence: Releases depend on community contributions; slower iteration than Microsoft-backed projects but maintains vendor independence

• Static output only, no runtime server component

  • Why: Simplifies deployment and reduces operational overhead
  • Consequence: No real-time search or dynamic content; search must be client-side or via external service like Algolia

• YAML as intermediate metadata format

  • Why: Enables decoupling of extraction from rendering and allows version control of API docs
  • Consequence: Additional processing step and storage overhead compared to direct markdown generation

• Template-based theming instead of CSS-only customization

  • Why: Allows complete structural control of output HTML
  • Consequence: Steeper learning curve for theme authors; template updates can break compatibility

• Real-time search capabilities (requires external indexing service)
• Authentication or access control (generates public-only static content)
• Dynamic content or user-generated modifications
• Non-.NET API documentation (REST/OpenAPI is secondary feature)
• Windows-only deployment (supports cross-platform via .NET)

1. Template build prerequisite: C# build fails if templates/ has not been built (npm install && npm run build required first). 2. Multi-language toolchain: Requires .NET 8+, Node 24.x, and npm in PATH; missing any breaks build. 3. Directory.Packages.props is authoritative: Do not manually edit project .csproj files for version pins; use Directory.Packages.props or dependabot updates will conflict. 4. xrefmap.json generation: Cross-reference resolution depends on xrefmap.json being generated during build; deleting it breaks link resolution. 5. Template localization complexity: XSLT and Go templates are mixed with TypeScript; breaking one template build breaks HTML generation for all sites.

• XREF (Cross-Reference) Maps — DocFX generates .xrefmap.json files to map type names to URLs so links between related types work automatically; understanding xref resolution is essential for debugging broken documentation links
• Document Processor Pipeline — DocFX chains multiple document processors (reflection → YAML → Markdown → HTML) in sequence; knowing this pipeline is critical for adding new file format support or debugging transformation bugs
• YAML Metadata Format — DocFX's intermediate representation for API metadata (see docs/docs/dotnet-yaml-format.md); understanding YAML structure is required to extend metadata extraction or customize API page generation
• Liquid Template Engine — DocFX uses Liquid (or similar template language) in Go Templates + XSLT to render final HTML from YAML metadata; required for customizing site layout and styling
• Monorepo Workspace Management — DocFX's Directory.Build.props and Directory.Packages.props centralize dependency management across hundreds of C# projects; understanding NuGet workspace patterns prevents version conflicts
• Static Site Generation with API Reflection — DocFX uniquely combines reflection metadata extraction (via Roslyn or manual YAML) with static HTML generation; this build-time approach enables SEO-friendly, version-locked documentation without runtime servers

• dotnet/Roslyn — Companion repo: docfx consumes Roslyn's semantic analysis output (.NET reflection metadata) to extract API documentation from source code
• dotnet/api-docs — Ecosystem repo: upstream source of .NET API documentation that docfx ingests and transforms; shows real-world docfx consumption at scale
• microsoft/rushstack — Related tooling: monorepo build system and npm publishing patterns applicable to docfx's template + C# dual build system
• jekyll/jekyll — Alternative static site generator in Ruby ecosystem; docfx's primary competitor for .NET docs, useful for architectural comparison
• build-it-yourself/asciidoctor — Parallel project: AsciiDoc → static site generator; handles similar markup-to-HTML pipeline but for Java ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for RtfDocumentProcessor and RtfBuildStep

The RTF code snippet examples exist in docs/codesnippet/Rtf/ (RtfDocumentProcessor.cs and RtfBuildStep.cs), but there's no evidence of corresponding unit tests in the repository. These are document processors that likely handle critical formatting logic. Adding thorough unit tests would improve reliability and serve as regression protection for RTF document handling.

• [ ] Create test files mirroring src structure for RTF processor components
• [ ] Add unit tests covering RtfDocumentProcessor.cs initialization and document processing
• [ ] Add unit tests covering RtfBuildStep.cs build step lifecycle
• [ ] Test edge cases: malformed RTF, special characters, hyperlinks in RTF (referenced in file path)
• [ ] Integrate tests into ci.yml workflow if not already present

Document missing configuration options in docs/docs/config.md

The repository has Directory.Build.props and Directory.Packages.props files which suggest MSBuild-based configuration, but the docs/docs/config.md file likely doesn't comprehensively document all configuration surface. Analyzing these property files and creating detailed configuration reference documentation would help users understand build customization options.

• [ ] Review Directory.Build.props and Directory.Packages.props for all configurable properties
• [ ] Check docfx.json structure and compare against docs/docs/config.md coverage
• [ ] Add missing property documentation with examples to docs/docs/config.md
• [ ] Document package version pinning and override patterns from Directory.Packages.props
• [ ] Add a new section for build-time customization with property examples

Create GitHub Actions workflow for spell-checking documentation against SpellingExclusions.dic

The repository has a SpellingExclusions.dic file indicating spelling validation is important, but there's no dedicated spell-check workflow visible in .github/workflows/. Adding a workflow that validates markdown and docs against this dictionary during CI would catch documentation quality issues early and keep docs/docs/ content consistent.

• [ ] Review existing .github/workflows/ files (ci.yml, lint.yml) to avoid duplication
• [ ] Choose or configure a spell-checking tool (e.g., cspell, aspell, or Timon) compatible with the exclusions dictionary
• [ ] Create .github/workflows/spell-check.yml that runs on pull requests targeting docs/
• [ ] Integrate SpellingExclusions.dic as the authority file for accepted terms
• [ ] Add spell-check job to ci.yml or keep as separate workflow with appropriate triggers

• Add missing unit tests for Go template rendering pipeline (docs/codesnippet/Rtf shows examples but no test coverage visible in file list for template edge cases like Hyperlink and RtfDocumentProcessor).
• Expand CONTRIBUTING.md troubleshooting section with a 'Build Diagnostics' subsection listing common failures (template build, node version mismatch, missing .NET SDK versions) and solutions.
• Create TypeScript/SCSS unit test suite for templates/ to cover CSS selector regressions and template variable injection; currently test coverage for frontend appears minimal vs. C# backend.

The dotnet/docfx repository demonstrates good security practices with presence of SECURITY.MD, dependabot configuration, and multi-workflow CI/CD setup. However, there are notable concerns: (1) The Dockerfile has critical issues including incomplete cleanup commands and lack of security hardening best practices, (2) Hardcoded dependency versions without clear update mechanisms, (3) Missing integrity verification for downloaded scripts and tools, (4) No visible secrets management or credential handling issues detected. The codebase appears to follow .NET Foundation standards, but Docker infrastructure hardening and supply chain security (verification

• High · Hardcoded Docker Image Version — Dockerfile - ARG DOCFX_VERSION=2.78.2. The Dockerfile uses a hardcoded DOCFX_VERSION (2.78.2) without version pinning best practices. While this specific version is old (likely from 2023-2024 timeframe), there's no mechanism to automatically update to patched versions. Additionally, the base image uses 'noble' tag which is not the most specific pinning available. Fix: Use specific semantic versioning with patch level. Consider using a more specific base image tag (e.g., 8.0-noble-20240101) and implement automated dependency scanning for security updates. Consider using Dependabot for Docker image updates.
• High · Incomplete Dockerfile Cleanup — Dockerfile - Last RUN instruction. The Dockerfile RUN command appears to be truncated (ends with 'rm -rf /va' without completing the path). This suggests incomplete layer cleanup which could leave sensitive files or unnecessary artifacts in the image, increasing attack surface and image size. Fix: Complete the cleanup command with full paths. Ensure all temporary files, package manager caches, and unnecessary tools are properly removed from final layers. Example: 'rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*'
• Medium · Overly Permissive File Deletion Pattern — Dockerfile - Multiple rm commands. The Dockerfile uses 'rm -f' and 'rm -rf' commands without error checking. While removing NuGet packages is good practice, the recursive removal without verification could potentially delete unintended files if paths are misconfigured. Fix: Use more explicit deletion patterns with proper error handling. Consider: 'set -e' at the beginning of RUN commands to fail on errors, or verify paths before deletion. Use 'find' with specific criteria instead of broad patterns.
• Medium · Missing Network Isolation Configuration — Dockerfile - Overall configuration. No explicit network security configuration visible in Dockerfile. The Docker image doesn't show implemented security best practices like disabling unnecessary network capabilities or using read-only root filesystem. Fix: Add security best practices: use 'USER' instruction to run as non-root, implement read-only root filesystem where possible, restrict capabilities using '--cap-drop', and consider network policies in orchestration environments.
• Medium · Playwright Installation Without Verification — Dockerfile - pwsh playwright.ps1 installation. The Dockerfile installs Playwright browser dependencies via PowerShell script without any integrity verification or signature validation. The script is run directly from the dotnet tools store. Fix: Verify script integrity using checksums before execution. Document the expected hash of playwright.ps1 and validate it. Consider pre-building the image with verified tools or using base images with pre-installed browsers.
• Low · Missing Security Policy Documentation — SECURITY.MD - Content not provided. While SECURITY.MD exists in the repository, the provided file structure shows it's present but content wasn't analyzed. Ensure the security policy is comprehensive and up-to-date with vulnerability reporting procedures. Fix: Ensure SECURITY.MD includes clear vulnerability disclosure process, supported versions, patching timelines, and responsible disclosure guidelines. Make it easily discoverable in repository root.
• Low · Dependabot Configuration May Be Incomplete — .github/dependabot.yml - Content not provided. The repository has .github/dependabot.yml, which is good practice, but without seeing its contents, the effectiveness cannot be verified. It may not cover all dependency types or have appropriate update frequency. Fix: Verify dependabot.yml covers: NuGet packages, Docker base images, GitHub Actions, and npm dependencies (if used). Configure appropriate version update strategies and security patch frequency set to immediate.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.