Search Results for

    Show / Hide Table of Contents

    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.
    • Improve this Doc
    In This Article
    Back to top Made with docfx