Build Configuration (docfx.json)

What the build controls

Build configuration contains settings for build. It defines

  1. which files will be included or excluded for build as content
  2. which files will be included or excluded for build as resources
  3. global metadata
  4. breadcrumb location
  5. configure the rendering template

Build Template

A template of build configuration:

{
  "build": {
    "content":
      [
        {
          "files": ["**/**.md"],
          "src": "api",
          "exclude": ["**/obj/**"]
        }
      ],
    "resource": [
        {
          "files": ["**/images/**"],
          "exclude": ["**/obj/**"]
        }
    ],
    "globalMetadata": {
        "ROBOTS": "NOINDEX, NOFOLLOW",
        "ms.sitesec": "library",
        "breadcrumb_path": "/openpublishing/breadcrumb/toc.json"
    },
    "fileMetadata": {
        "priority": {
            "obj/docfx/**": 1.0,
            "**.md": 2.5,
            "spec/**.md": 3,
            "tutorial/**.md": 1.2
         },
        "keywords": {
            "obj/docfx/**": ["API", "Reference"],
            "spec/**.md": ["Spec", "Conceptual"],
            "**/*markdown.md": ["DFM", "Spec"]
        }
    },
    "externalReference": [
    ],
    "template": "op.html",
    "dest": "openpublishing/docs"
  }
}

Build Properties

Properties for build

Key Description
content OPTIONAL. Contains all the files to generate documentation, including metadata yml files and conceptual md files. The files secction contains all the project files to be generatedhave API generated. The 'src' section allows you to build all the content in the folder specified without having the folder name in the URL.
resource OPTIONAL. Contains all the resource files that conceptual and metadata files dependent on, e.g. image files. name-files file mapping with several ways to define it.
overwrite OPTIONAL. Contains all the conceputal files which contains yaml header with uid and is intended to override the existing metadata yml files. name-files file mapping with several ways to define it.
externalReferences OPTIONAL.
globalMetadata OPTIONAL. Contains metadata that will be applied to every file, in key-value pair format. For example, you can define "_appTitle": "This is the title" in this section, and when applying template default, it will be part of the page title as defined in the template.
fileMetadata OPTIONAL. Contains metadata that will be applied to individual files, in key-value pair format.
template OPTIONAL. The templates applied to each file in the documentation. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If ommited, embedded default template will be used.
theme OPTIONAL. The themes applied to the documentation. Theme is used to customize the styles generated by template. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If ommited, no theme will be applied, the default theme inside the template will be used.

Publishing to the root folder - how to.

Just remove the destination folder "dest" except for the final line within the brackets. Example: ... }, "fileMetadata": {}, "template": [], "dest": "vsts-docs-rest-apis" } }

Build Troubleshooting

Q: My images are not displaying.

A: Make sure you have included the file extension you want under the "resource->file" area. Also check that those file extensions are not in the "resource->exclude" area.