Doc-as-code: docfx.exe User Manual

• 1/24/2022
• 20 minutes to read
• • 

0. Introduction

docfx.exe is used to generate documentation for programs. It has the ability to:

1. Extract language metadata for programing languages as defined in Metadata Format Specification. Currently C#, VB and F# are supported. The language metadata will be saved with YAML format as described in YAML 1.2.
2. Look for available conceptual files as provided and link it with existing programs with syntax described in Section 3. Work with Metadata in Markdown. Supported conceptual files are plain text files, html files, and markdown files.
3. Generate documentation to a. Visualize language metadata, with extra content provided by linked conceptual files using syntax described in Section 3. Work with Metadata in Markdown. b. Organize and render available conceptual files. It can be easily cross-referenced with language metadata pages. We support Docfx Flavored Markdown(DFM) for writing conceptual files. DFM supports all Github Flavored Markdown(GFM) syntax with 2 exceptions when resolving list. It also adds several new features including file inclusion, cross reference, and yaml header. For detailed description about DFM, please refer to DFM.

Currently generating documentations to a client only website is supported. The generated website can be easily published to whatever platform such as Github Pages and Azure Website with no extra effort.

Generating offline documentation such as PDF is also supported now.

1. Syntax

docfx <command> [<args>]

2. Commands

2.0 Init command docfx init

docfx init helps generate an docfx.json file.

2.1 Help command docfx help

docfx help -a list available subcommands.

docfx help <command> to read about a specific subcommand

2.2 Extract language metadata command docfx metadata

Syntax

docfx metadata [<projects>] [--property <n1>=<v1>;<n2>=<v2>]

Layout

|-- <metadata folder>
      |-- api
      |     |-- <namespace>.yml
      |     |-- <class>.yml
      |-- toc.yml
      |-- index.yml

2.2.1 Optional <projects> argument

<projects> specifies the projects to have metadata extracted. There are several approaches to extract language metadata.

1. From a supported file or file list Supported file extensions include .csproj, .vbproj, .sln, project.json, dll assembly file, .cs source file and .vb source file.

   Multiple files are separated by whitespace, e.g. docfx metadata Class1.cs a.csproj

   NOTE

   Glob pattern is NOT supported in command line options.

2. From docfx.json file, as described in Section3.

3. If the argument is not specified, docfx.exe will try reading docfx.json under current directory.

The default output folder is _site/ folder if it is not specified in docfx.json under current directory.

2.2.2 Command option --shouldSkipMarkup

If adding option --shouldSkipMarkup in metadata command, it means that DocFX would not render triple-slash-comments in source code as markdown.

e.g. docfx metadata --shouldSkipMarkup

2.2.3 Command option --property <n1>=<v1>;<n2>=<v2>

An optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to msbuild via the /property:=;= command line argument. For example: docfx metadata --property TargetFramework=net46 generates metadata files with .NET framework 4.6. This command can be used when the project supports multiple TargetFrameworks.

2.3 Generate documentation command docfx build

Syntax

docfx build [-o:<output_path>] [-t:<template folder>]

docfx build generates documentation for current folder.

If toc.yml or toc.md is found in current folder, it will be rendered as the top level TABLE-OF-CONTENT. As in website, it will be rendered as the top navigation bar. Path in toc.yml or toc.md are relative to the TOC file.

toc.yml syntax toc.yml is an array of items. Each item can have following properties:

toc.yml Sample

- name: Home
  href: articles/Home.md
- name: Roslyn Wiki
  href: roslyn_wiki/
- name: Roslyn API
  href: api_roslyn/
  homepage: homepages/roslyn_language_features.md

toc.md Sample

## [Home](articles/Home.md)
## [Roslyn Wiki](roslyn_wiki/)
## [Roslyn API](api_roslyn/)

2.3.1 Optional <output_path> argument

The default output folder is _site/ folder

2.3.2 Optional <template folder> argument

If specified, use the template from template folder

Template Folder Structure

|-- <template folder>
      |-- index.html
      |-- styles
      |     |-- docascode.css
      |     |-- docascode.js
      |-- template
      |     |-- toc.html
      |     |-- navbar.html
      |     |-- yamlContent.html
      |-- favicon.ico
      |-- logo.ico

2.4 Generate PDF documentation command docfx pdf

Syntax

docfx pdf [<config_file_path>] [-o:<output_path>]

docfx pdf generates PDF for the files defined in config file, if config file is not specified, docfx tries to find and use docfx.json file under current folder.

Current design is that each TOC file generates a corresponding PDF file. Walk through Walkthrough: Generate PDF Files to get start.

If cover.md is found in a folder, it will be rendered as the cover page.

3. docfx.json Format

Top level docfx.json structure is key-value pair. key is the name of the subcommand, current supported subcommands are metadata and build.

3.1 Properties for metadata

Metadata section defines an array of source projects and their output folder. Each item has src and dest property. src defines the source projects to have metadata generated, which is in File Mapping Format. Detailed syntax is described in 4. Supported name-files File Mapping Format below. dest defines the output folder of the generated metadata files.

Sample

{
  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.csproj"],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": "../src"
        }
      ],
      "dest": "obj/docfx/api/dotnet",
      "shouldSkipMarkup": true,
      "properties": {
          "TargetFramework": "netstandard1.3"
      }
    },
    {
      "src": [
        {
          "files": ["**/*.js"],
          "src": "../src"
        }
      ],
      "dest": "obj/docfx/api/js",
      "useCompatibilityFileName": true,
      "properties": {
          "TargetFramework": "net46"
      }
    }
  ]
}

3.2 Properties for build

3.2.1 Templates and Themes

Templates are used to transform YAML files generated by docfx to human-readable pages. A page can be a markdown file, a html file or even a plain text file. Each YAML file will be transformed to ONE page and be exported to the output folder preserving its relative path to src. For example, if pages are in HTML format, a static website will be generated in the output folder.

Theme is to provide general styles for all the generated pages. Files inside a theme will be generally COPIED to the output folder. A typical usage is, after YAML files are transformed to HTML pages, well-designed CSS style files in a Theme can then overwrite the default styles defined in template, e.g. main.css.

There are two ways to use custom templates and themes.

To use a custom template, one way is to specify template path with --template (or -t) command option, multiple templates must be separated by , with no spaces. The other way is to set key-value mapping in docfx.json:

{
  ...
  {
    "build" :
    {
      ...
      "template": "custom",
      ...
    }
  ...
}

{
  ...
  {
    "build" :
    {
      ...
      "template": ["default", "X:/template/custom"],
      ...
    }
  ...
}

To custom theme, one way is to specify theme name with --theme command option, multiple themes must be separated by , with no spaces. The other way is to set key-value mapping in docfx.json as similar to defining template. Also, both .zip file and folder are supported.

Please refer to How to Create Custom Templates to create custom templates.

Sample

{
  "build": {
    "content":
      [
        {
          "files": ["**/*.yml"],
          "src": "obj/docfx"
        },
        {
          "files": ["tutorial/**/*.md", "spec/**/*.md", "spec/**/toc.yml"]
        },
        {
          "files": ["toc.yml"]
        }
      ],
    "resource": [
        {
          "files": ["spec/images/**"]
        }
    ],
    "overwrite": "apispec/*.md",
    "externalReference": [
    ],
    "globalMetadata": {
      "_appTitle": "DocFX website",
      "_gitContribute": {
        "repo": "https://github.com/org/repo",
        "branch": "dev",
        "apiSpecFolder": "docs-ref-overwrite"
      }
    },
    "dest": "_site",
    "template": "default"
  }
}

3.2.2 Reserved Metadata

After passing values through global metadata or file metadata, DocFX can use these metadata in templates to control the output html. Reserved metadatas:

3.2.3 Separated metadata files for global metadata and file metadata

There're three ways to set metadata for a file in DocFX:

1. using global metadata, it will set metadata for every file.
2. using file metadata, it will set metadata for files that match pattern.
3. using YAML header, it will set metadata for current file.

In above ways, the later way will always overwrite the former way if the same key of metadata is set.

Here we will show you how to set global metadata and file metadata using separated metadata files. Take global metadata for example, you can set globalMetadataFiles in docfx.json or --globalMetadataFiles in build command line. The usage of fileMetadataFiles is the same as globalMetadataFiles.

There're some metadata file examples:

• globalMetadata file example

  {
      "_appTitle": "DocFX website",
      "_enableSearch": "true"
  }
  

• fileMetadata file example

  {
      "priority": {
          "**.md": 2.5,
          "spec/**.md": 3
      },
      "keywords": {
          "obj/docfx/**": ["API", "Reference"],
          "spec/**.md": ["Spec", "Conceptual"]
      },
      _noindex: {
          "articles/**/article.md": true
      }
  }
  

There're some examples about how to use separated metadata files.

• use globalMetadataFiles in docfx.json

  ...
  "globalMetadataFiles": ["global1.json", "global2.json"],
  ...
  

• use --globalMetadataFiles in build command line

  docfx build --globalMetadataFiles global1.json,global2.json
  

• use fileMetadataFiles in docfx.json

  ...
  "fileMetadataFiles": ["file1.json", "file2.json"],
  ...
  

• use --fileMetadataFiles in build command line

  docfx build --fileMetadataFiles file1.json,file2.json
  

Note that, metadata set in command line will merge with metadata set in docfx.json.

• If same key for global metadata was set, the order to be overwritten would be(the later one will overwrite the former one):

  1. global metadata from docfx config file
  2. global metadata from global metadata files
  3. global metadata from command line

• If same file pattern for file metadata was set, the order to be overwritten would be(the later one will overwrite the former one):

  1. file metadata from docfx config file
  2. file metadata from file metadata files

Given multiple metadata files, the behavior would be undetermined, if same key is set in these files.

3.2.4 Xref service url pattern

Xref service url pattern will exact url by following steps:

1. Replace environment variables.

   • Syntax: {%variableName%}
   • Process: load variable value from enviroment variables, replace the source content.

2. Extract post pipelines.

   • Syntax: |> pipelineName parameter1 parameter2 ...
   • Process: load pipeline, and extract parameters, remove from url.
   • Current pipeline only contains: removeHost, addQueryString, pluggable pipeline will be add later.

3. Runtime replace variables.

   • Syntax: {varName}
   • Process: replace the source content to the value of variable (uri data encoded).

e.g.:
Environment variables: test = hello
Available Pipeline: removeHost
Variable: uid = testuid1
Url pattern: http://{%test%}.contoso.com/?uid={uid}|> removeHost

It will run as following steps:

1. Replace environment variables, http://hello.contoso.com/?uid={uid}|> removeHost.
2. Extract post pipelines, http://hello.contoso.com/?uid={uid}, and append a post pipeline removeHost.
3. Runtime replace variables, http://hello.contoso.com/?uid=testuid.
4. Send request to http://hello.contoso.com/?uid=testuid, and get response from site.
5. Run post pipeline removeHost.

3.2.5 SitemapOptions

The SitemapOptions is to configure the values for generating sitemap.xml file.

In the following sample settings, the yml files inside api folder are with priority 0.3 while Markdown files are with priority 0.8 and with a different baseUrl.

Sample settings:

"build": {
    "sitemap":{
        "baseUrl": "https://dotnet.github.io/docfx",
        "priority": 0.1,
        "changefreq": "monthly",
        "fileOptions":{
            "**/api/**.yml": {
                "priority": 0.3,
                "lastmod": "2001-01-01",
            },
            "**/GettingStarted.md": {
                "baseUrl": "https://dotnet.github.io/docfx/conceptual",
                "priority": 0.8,
                "changefreq": "daily"
            }
        }
    }
}

Possible generated sitemap.xml:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://dotnet.github.io/docfx/api/System.String.html</loc>
    <lastmod>2001-01-01T00:00:00.00+08:00</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://dotnet.github.io/docfx/conceptual/GettingStarted.html</loc>
    <lastmod>2017-09-21T10:00:00.00+08:00</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.3</priority>
  </url>
  <url>
    <loc>https://dotnet.github.io/docfx/ReadMe.html</loc>
    <lastmod>2017-09-21T10:00:00.00+08:00</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.1</priority>
  </url>
</urlset>

3.3 Properties for pdf

pdf supports ALL the properties for build, besides that, the following table lists additional properties specified for pdf only.

3.3.1 Properties for the wkhtmltopdf Key

4. Supported File Mapping Format

There are several ways to define file mapping.

4.1 Array Format

This form supports multiple file mappings, and also allows additional properties per mapping. Supported properties:

"key": [
  {"files": ["file1", "file2"], "dest": "dest1"},
  {"files": "file3", "dest": "dest2"},
  {"files": ["file4", "file5"], "exclude": ["file5"], "src": "folder1"},
  {"files": "Example.yml", "src": "v1.0", "dest":"v1.0/api", "version": "v1.0"},
  {"files": "Example.yml", "src": "v2.0", "dest":"v2.0/api", "version": "v2.0"}
]

4.2 Compact Format

"key": ["file1", "file2"]

4.3 Glob Pattern

DocFX uses Glob to support glob pattern in file path. It offers several options to determine how to parse the Glob pattern:

• caseSensitive: Default value is false. If set to true, the glob pattern is case sensitive. e.g. *.txt will not match 1.TXT. For OS Windows, file path is case insensitive while for Linux/Unix, file path is case sensitive. This option offers user the flexibility to determine how to search files.
• supportBackslash: Default value is true. If set to true, \ will be considered as file path separator. Otherwise, \ will be considered as normal character if escape is set to true and as escape character if escape is set to false. If escape is set to true, \\ should be used to represent file path separator.
• escape: Default value is false. If set to true, \ character is used as escape character, e.g. \{\}.txt will match {}.txt.

In general, the glob pattern contains the following rules:

1. * matches any number of characters, but not /
2. ? matches a single character, but not /
3. ** matches any number of characters, including /, as long as it's the only thing in a path part
4. {} allows for a comma-separated list of OR expressions

SAMPLES

5. Q & A

1. Do we support files outside current project folder(the folder where docfx.json exists)?
   A: YES. DO specify src and files outside of current folder will be copied to output folder keeping the same relative path to src.
2. Do we support output folder outside current project folder(the folder where docfx.json exists)?
   A: YES.
3. Do we support referencing files outside of current project folder(the folder where docfx.json exists)?
   A: NO.