Implement comprehensive DocFX documentation site with GitHub Pages deployment

[Copilot]

Adds complete DocFX-based documentation covering library features, usage patterns, and API reference with automated GitHub Pages deployment.

Documentation Structure

• Landing page - Quick navigation, feature overview, installation
• Core articles (60k words) - Introduction, getting started, core concepts, workflows, best practices
• Tutorials (23k words) - Basic and advanced step-by-step guides
• Sample docs (21k words) - Detailed documentation for MinimalApi, WebApp, Worker, and Console samples
• API reference (10k words) - All 40+ MSBuild properties and 7 tasks, auto-generated from XML comments

CI/CD

• GitHub Actions workflow builds docs on push to main
• Automatic deployment to GitHub Pages
• PR builds for preview
• Uses actions/download-artifact@v4.1.3 (patched CVE)

Configuration

# docs/docfx.json
{
  "metadata": [{
    "src": [{ "files": ["src/JD.MSBuild.Containers.Tasks/**.csproj"] }],
    "dest": "api"
  }],
  "build": {
    "template": ["default", "modern"],
    "globalMetadata": {
      "_enableSearch": true,
      "_gitContribute": {
        "repo": "https://github.com/JerrettDavis/JD.MSBuild.Containers"
      }
    }
  }
}

Documentation will be available at: https://jerrettdavis.github.io/JD.MSBuild.Containers/

Total: 114k words across 70+ pages covering all library capabilities.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature][DocFX] Implement Comprehensive Documentation Site</issue_title>
<issue_description>### Summary

We need a fully realized documentation site for JD.MSBuild.Containers built with DocFX that gives users a clear, professional, and searchable resource covering:

• Workflows and usage guides
• Sample application documentation
• API reference
• Best practices and patterns
• Tutorials for common scenarios

We can take cues from existing documentation sites in other JerrettDavis repos, such as:

• https://github.com/jerrettdavis/tinybdd
• https://github.com/jerrettdavis/experimentframework
• https://github.com/jerrettdavis/patternkit
• https://github.com/jerrettdavis/jd.efcpt.build

These repos have excellent documentation structures we can use as inspiration or skeletons.

---

🗺 Documentation Goals

The goal of this feature is to provide:

• A comprehensive, easy-to-navigate docs site
• Clear ToC and navigation structure
• Consistent writing style, formatting, and tone
• Code samples, workflows, diagrams (where applicable)
• Generated API reference from source XML documentation
• Guides that help users from first clone → to building → to containerizing

---

🧱 Proposed Docs Tree (File + Nav Structure)

Below is a proposed directory and ToC structure for /docs:

/docs
├── api/                        # DocFX-generated API reference
├── assets/                     # Site assets (images, CSS overrides, diagrams)
├── articles/                  # Conceptual guides
│   ├── introduction.md
│   ├── getting-started.md
│   ├── concepts.md
│   ├── workflows.md
│   └── best-practices.md
├── samples/                   # Sample-focused documentation
│   ├── sample-overview.md
│   ├── sample-webapi.md
│   └── sample-workflow.md
├── tutorials/                # Step-by-step guides
│   ├── tutorial-basic.md
│   └── tutorial-advanced.md
├── toc.yml                    # Top-level table of contents
├── docfx.json                 # DocFX config
└── README.md                  # Landing page used by DocFX

---

📌 Suggested ToC (toc.yml)

- name: Home
  href: index.md

- name: Introduction
  href: articles/introduction.md

- name: Getting Started
  href: articles/getting-started.md

- name: Concepts
  items:
    - name: What is JD.MSBuild.Containers?
      href: articles/concepts.md
    - name: Core Concepts
      href: articles/concepts.md#core-concepts

- name: Workflows
  href: articles/workflows.md

- name: Tutorials
  items:
    - name: Basic Tutorial
      href: tutorials/tutorial-basic.md
    - name: Advanced Tutorial
      href: tutorials/tutorial-advanced.md

- name: Samples
  items:
    - name: Sample Overview
      href: samples/sample-overview.md
    - name: Web API Sample
      href: samples/sample-webapi.md

- name: API Reference
  href: api/index.md

- name: Best Practices
  href: articles/best-practices.md

---

🧠 Guide for Implementor

✏️ Writing Style & Tone

• Professional, clear, and concise
• Assume readers range from new container users to seasoned .NET devs
• Prefer actionable language (“Do this” → “Then this”)
• Use code blocks liberally
• Explain why as well as how
• Use consistent naming with the library

Example:

### Why this matters

Containers are ephemeral.
JD.MSBuild.Containers enables consistent reproducible builds without Dockerfiles,
so users can focus on code, not orchestration.

### How it works

1. Add package references
2. Configure container settings
3. Run build …

---

🧩 Section Guidance

📍 introduction.md

• Project overview
• Vision and scope
• When to use this library
• High-level architecture

📍 getting-started.md

• Prerequisites
• Installing the library
• Local development workflow
• Quickstart example

📍 concepts.md

• Key components
• MSBuild tasks explained
• How container builds work under the hood

📍 workflows.md

• Local build flows
• CI workflows (GitHub actions example)
• Consuming local NuGet packages

📍 tutorials/*.md

• Step-by-step guides
• From blank project → containerized app
• Include code snippets and expected outputs

📍 samples/*.md

• Detailed sample documentation
• Architecture diagrams (optional)
• Commands and explanations

📍 api/

• Generated by DocFX
• Includes XML docs
• Cross-linkable from conceptual docs

---

🧪 Validation & CI Integration

As part of this feature, include:

• CI validation to build the doc site on push
• A staging site deployment (GitHub Pages or GitHub Actions)
• Linting checks (link validation, broken references)

---

📌 Acceptance Criteria

• /docs directory exists
• DocFX config is configured and builds a site
• TOC...

• Fixes [Feature][DocFX] Implement Comprehensive Documentation Site #8

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

Code Coverage

Summary
  Generated on: 01/17/2026 - 06:09:49
  Coverage date: 01/17/2026 - 06:09:47
  Parser: Cobertura
  Assemblies: 0
  Classes: 0
  Files: 0
  Line coverage: 
  Covered lines: 0
  Uncovered lines: 0
  Coverable lines: 0
  Total lines: 0
  Covered branches: 0
  Total branches: 0
  Method coverage: 
  Full method coverage: 
  Covered methods: 0
  Fully covered methods: 0
  Total methods: 0
No assemblies have been covered.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (52f134d) to head (9163113).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@    Coverage Diff    @@
##   main   #9   +/-   ##
=========================
=========================

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.