Config

Docfx uses docfx.json as the config file for the site. Most docfx commands operate in a directory containing docfx.json.

The build config determines what files are included in the site:

{
  "build": {
    "content": [
      { "files": "**/*.{md,yml}", "exclude": "**/include/**" }
    ],
    "resource": [
      { "files": "**/images/**" }
    ]
  }
}

The content config defines glob patterns of files that are transformed to HTML by the build process. It is usually the markdown files and auto-generated API YAML files.

The resource config defines static resources copied to output as is.

URL Management

URL is determined by the file path relative to docfx.json. Docfx uses “Ugly URLs”: a file named docs/urls.md is accessible from the docs/urls.html URL.

To customize URL pattern for a directory, use the src property to remove the directory name from the URL, and use the dest property to insert an URL prefix:

{
  "build": {
    "content": [
      { "files": "**/*.{md,yml}", "src": "articles", "dest": "docs" }
    ]
  }
}

In this example, files in the articles directory uses docs as the base URL: The articles/getting-started/installation.md file is accessible by the docs/getting-started/installation.html URL.

Metadata

Metadata are attributes attached to an file. It helps shape the look and feel of a page and provides extra context to the article.

To add metadata to an article, use "YAML Front Matter" markdown extension syntax:

---
title: a title
description: a description
---

Some metadata attributes are consistent across a set of content. Use the globalMetadata property in docfx.json to apply the same metadata to all articles:

{
  "build": {
    "globalMetadata": {
      "_appTitle": "My App"
    }
  }
}

To apply identical metadata values to a folder or a set of content, use the fileMetadata config:

{
  "build": {
    "fileMetadata": {
      "_appTitle": {
        "articles/dotnet/**/*.md": ".NET",
        "articles/typescript/**/*.md": "TypeScript"
      }
    }
  }
}

When the same metadata key is defined in multiple places, YAML Front Matter takes precedence over fileMetadata which in turn takes precedence over globalMetadata.

Predefined Metadata

Here is a list of predefined metadata recognized by the default docfx site template to customize basic site settings:

Name	Type	Description
_appTitle	string	A string append to every page title.
_appFooter	string	The footer HTML.
_appLogoPath	string	App logo URL path.
_appFaviconPath	string	Favicon URL path.
_enableSearch	bool	Whether to show the search box.
_enableNewTab	bool	Whether to open external links in a new tab.
_disableNavbar	bool	Whether to show the navigation bar.
_disableBreadcrumb	bool	Whether to show the breadcrumb.
_disableToc	bool	Whether to show the TOC.
_disableAffix	bool	Whether to show the right rail.
_noindex	bool	Whether to include in search results
_disableContribution	bool	Whether to show the "Improve this Doc" and _"View Source" buttons.
_gitContribute	object	Defines the repo and branch property of git links.
_gitUrlPattern	string	URL pattern of git links.
redirect_url	string	Redirects the current page to the specified redirect URL. URLs can be relative.

Tip

Docfx produces the right git links for major CI pipelines including GitHub, GitLab, Azure Pipelines, AppVeyor, TeamCity, Jenkins. _gitContribute and _gitUrlPattern are optional on these platforms.

Sitemap

Docfx produces a sitemap.xml about the pages on your site for search engines like Google to crawl your site more efficiently.

The sitemap option in docfx.json controls how sitemaps are generated:

{
  "build": {
    "sitemap": {
      "baseUrl": "https://dotnet.github.iodocfx",
      "priority": 0.1,
      "changefreq": "monthly"
    }
  }
}

Where:

• baseUrl is the base URL for the website. It should start with http or https and end with a trailing slash. For example, https://dotnet.github.io/docfx/.
• lastmod is the date of last modification of the page. If not specified, docfx sets the date to the build time.
• changefreq determines how frequently the page is likely to change. Valid values are always, hourly, daily, weekly, monthly, yearly, never. Default to daily.
• priority is the priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.
• fileOptions is a per file config of the above options. The key is the file glob pattern and value is the sitemap options.