Dotnet Api Docs

Out of scope

• XML documentation comment syntax and authoring -- see [skill:dotnet-xml-docs]
• OpenAPI spec generation and configuration -- see [skill:dotnet-openapi]
• CI/CD deployment pipelines for documentation sites -- see [skill:dotnet-gha-deploy]
• Documentation platform selection and initial setup -- see [skill:dotnet-documentation-strategy]
• Changelog generation tooling and SemVer versioning -- see [skill:dotnet-release-management]

Cross-references: [skill:dotnet-xml-docs] for XML doc comment authoring, [skill:dotnet-openapi] for OpenAPI generation, [skill:dotnet-gha-deploy] for doc site deployment pipelines, [skill:dotnet-documentation-strategy] for platform selection, [skill:dotnet-release-management] for changelog tooling and versioning.

DocFX Setup for .NET API Reference

DocFX generates API reference documentation directly from .NET assemblies and XML documentation comments. It is the only documentation tool with native docfx metadata extraction from .NET projects.

Installation

# Install DocFX as a .NET global tool
dotnet tool install -g docfx

# Or as a local tool (recommended for team consistency)
dotnet new tool-manifest
dotnet tool install docfx

```text

### Configuration (`docfx.json`)

```json

{
  "metadata": [
    {
      "src": [
        {
          "files": ["src/**/*.csproj"],
          "exclude": ["**/bin/**", "**/obj/**"],
          "src": ".."
        }
      ],
      "dest": "api",
      "properties": {
        "TargetFramework": "net8.0"
      },
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": ["api/**.yml", "api/index.md"]
      },
      {
        "files": ["articles/**.md", "articles/**/toc.yml", "toc.yml", "*.md"]
      }
    ],
    "resource": [
      {
        "files": ["images/**"]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": ["default", "modern"],
    "postProcessors": ["ExtractSearchIndex"],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false,
    "globalMetadata": {
      "_appTitle": "My.Library API Reference",
      "_appFooter": "Copyright 2024 My Company",
      "_enableSearch": true,
      "_enableNewTab": true
    }
  }
}

```text

### Metadata Extraction

The `metadata` section controls how DocFX extracts API information from .NET projects:

```bash

# Generate API metadata YAML files from projects
docfx metadata docfx.json

# This creates YAML files in the api/ directory:
#   api/MyLibrary.WidgetService.yml
#   api/MyLibrary.Widget.yml
#   api/toc.yml

```yaml

**Key metadata configuration options:**

| Property                     | Purpose                       | Default                |
| ---------------------------- | ----------------------------- | ---------------------- |
| `src.files`                  | Project files to extract from | Required               |
| `dest`                       | Output directory for YAML     | `api`                  |
| `properties.TargetFramework` | TFM to build against          | Project default        |
| `disableGitFeatures`         | Skip git blame info           | `false`                |
| `filter`                     | Path to API filter YAML       | None (all public APIs) |

### API Filtering

Exclude internal types from the generated documentation:

```yaml

# filterConfig.yml
apiRules:
  - exclude:
      uidRegex: ^MyLibrary\.Internal\.
      type: Namespace
  - exclude:
      hasAttribute:
        uid: System.ComponentModel.EditorBrowsableAttribute
        ctorArguments:
          - System.ComponentModel.EditorBrowsableState.Never

```text

Reference the filter in `docfx.json`:

```json

{
  "metadata": [
    {
      "filter": "filterConfig.yml"
    }
  ]
}

```yaml

### Template Customization

DocFX supports template overrides for custom branding:

```text

docs/
  templates/
    custom/
      styles/
        main.css          # Custom CSS overrides
      partials/
        head.tmpl.partial # Custom head section (analytics, fonts)
        footer.tmpl.partial

```csharp

Reference custom templates in `docfx.json`:

```json

{
  "build": {
    "template": ["default", "modern", "templates/custom"]
  }
}

```text

### Cross-Referencing Between Pages

DocFX supports `uid`-based cross-references between API pages and conceptual articles:

```markdown

<!-- In a conceptual article -->

See the @MyLibrary.WidgetService.CreateWidgetAsync(System.String) method for details.

For the full API, see <xref:MyLibrary.WidgetService>.

```text

```yaml

# In an API YAML override file (api/MyLibrary.WidgetService.yml)
# Add links to conceptual articles