Getting Started

Relevant source files

• README.md
• src/docfx/Extensions/SpectreConsoleExtensions.cs
• src/docfx/Models/InitCommandOptions.cs
• src/docfx/Program.cs
• test/docfx.Tests/CommandLineTest.cs

This guide walks you through installing DocFX, creating your first documentation project, and building a documentation site. For detailed information about specific commands, see Command Line Interface. For configuration options, see Configuration System.

Installation

DocFX is distributed as a .NET global tool. Install it using the .NET CLI:

This command installs the docfx executable globally, making it available from any directory. The tool requires .NET 8.0 or later runtime.

For nightly builds with the latest features, DocFX publishes preview packages to GitHub Packages To install a nightly build:

Sources: README.md25-43

Creating a New Project

Using the Init Command

The init command creates a new DocFX project with sensible defaults. To create a project interactively:

For non-interactive project creation (useful in CI/CD environments), use the -y flag:

The InitCommand class src/docfx/Models/InitCommand.cs14-165 prompts for the following configuration:

Prompt	Default	Purpose
Name	mysite	Site name used in _appName and _appTitle metadata
Generate .NET API documentation?	true	Whether to include metadata extraction configuration
.NET projects location	src	Directory containing .csproj files
Markdown docs location	docs	Directory for conceptual documentation
Enable site search?	true	Adds search functionality to the site
Enable PDF?	true	Enables PDF generation capabilities

Sources: src/docfx/Models/InitCommand.cs16-31

Generated Project Structure

Diagram: Files produced by InitCommand (default layout)

The key files created are:

• docfx.json: Main configuration file containing metadata extraction settings, build configuration, and global metadata src/docfx/Models/InitCommand.cs34-68
• toc.yml: Root table of contents defining site navigation src/docfx/Models/InitCommand.cs78-88
• index.md: Homepage with landing page layout src/docfx/Models/InitCommand.cs90-103
• docs/: Directory containing conceptual documentation files src/docfx/Models/InitCommand.cs105-121

Sources: src/docfx/Models/InitCommand.cs70-122

Understanding the docfx.json Configuration

The generated docfx.json includes three main sections:

Metadata Section

When .NET API documentation is enabled, the metadata section configures code analysis:

This tells DocFX to:

1. Search for .csproj files in the ../src directory relative to docfx.json
2. Extract API metadata using Roslyn code analysis
3. Output YAML files to the api/ directory

Sources: src/docfx/Models/InitCommand.cs37-46

Build Section

The build section defines content sources, output location, and templates:

Sources: src/docfx/Models/InitCommand.cs48-67

Building Documentation

Basic Build Workflow

Diagram: CLI command classes and their delegated execution targets

Sources: src/docfx/Models/DefaultCommand.cs23-61 src/docfx/Models/BuildCommand.cs15-32 src/docfx/Models/MetadataCommand.cs12-19 src/docfx/Models/PdfCommand.cs13-22

Default Command (All-in-One)

The simplest way to build documentation is using the default command, which runs metadata extraction, site build, and PDF generation:

Or simply:

The DefaultCommand executes the following pipeline