Table of Contents

Template

Template defines the appearance of the website.

Docfx ships several built-in templates. We recommend using the modern template that matches the look and feel of this site. It supports dark mode, more features, rich customization options and.

Use the modern template by setting the template property to ["default", "modern"]:

{
  "build": {
    "template": [
      "default",
      "modern"
    ]
  }
}

Additional templates are available at the Template Gallery.

Template Metadata

The easiest way of customizing the the appearance of pages is using metadata. Here is a list of predefined metadata:

Name Type Description
_appTitle string A string append to every page title.
_appName string The name of the site displayed after logo.
_appFooter string The footer HTML.
_appLogoPath string Path to the app logo.
_appLogoUrl string URL for the app logo.
_appFaviconPath string Favicon URL path.
_enableSearch bool Whether to show the search box.
_noindex bool Whether to include in search results
_disableContribution bool Whether to show the "Edit this page" button.
_gitContribute object Defines the repo and branch property of git links.
_gitUrlPattern string URL pattern of git links.
_disableNewTab bool Whether to render external link indicator icons and 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.
_disableNextArticle bool Whether to show the previous and next article link.
_disableTocFilter bool Whether to show the table of content filter box.
_googleAnalyticsTagId string Enables Google Analytics web traffic analysis.
_lang string Primary language of the page. If unset, the <html> tag will not have lang property.
_layout string Determines the layout of the page. Supported values are landing and chromeless.
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.

Custom Template

To build your own template, create a new folder and add it to template config in docfx.json:

{
  "build": {
    "template": [
      "default",
      "modern",
      "my-template" // <-- Path to custom template
    ]
  }
}

Add your custom CSS file to my-template/public/main.css to customize colors, show and hide elements, etc. This is an example stylesheet that adjust the font size of article headers.

/* file: my-template/public/main.css */
article h1 {
  font-size: 40px;
}

You can also use CSS variables to adjust the templates. There are many predefined CSS variables in Bootstrap that can be used to customize the site:

/* file: my-template/public/main.css */
body {
  --bs-link-color-rgb: 66, 184, 131 !important;
  --bs-link-hover-color-rgb: 64, 180, 128 !important;
}

The my-template/public/main.js file is the entry JavaScript file to customize docfx site behaviors. This is a basic setup that changes the default color mode to dark and adds some icon links in the header:

/* file: my-template/public/main.js */
export default {
  defaultTheme: 'dark',
  iconLinks: [
    {
      icon: 'github',
      href: 'https://github.com/dotnet/docfx',
      title: 'GitHub'
    },
    {
      icon: 'twitter',
      href: 'https://twitter.com',
      title: 'Twitter'
    }
  ]
}

You can add custom startup scripts in main.js using the start option:

export default {
  start: () => {
    // Startup script goes here
  },
}

You can also configure syntax highlighting options using the configureHljs option:

export default {
  configureHljs: (hljs) => {
    // Customize hightlight.js here
  },
}

See this example on how to enable bicep syntax highlighting.

More customization options are available in the docfx options object.

Edit this page