bdoctor.json

The bdoctor.json file sits in the root of your project and holds the settings which stay the same on every run. It gets created for you when you initialize your project with bdoctor init.

Simple options

You can provide the same flags and values like in the parameters. Parameters can override what is defined in the bdoctor.json. Be sure to use the whole argument names, and not the shortcodes.

{
  "folder": "./src",
  "url": "https://<tenant>.sharepoint.com/sites/<documentation>",
  ...
}

The options which got introduced in v2.0.0 can be defined in the bdoctor.json file as well, so you do not need to repeat them on every run:

{
  "$schema": "https://cloud13.blob.core.windows.net/public/bdoctor/schema/2.4.0.json",
  "url": "https://<tenant>.sharepoint.com/sites/<documentation>",
  "appId": "<appId>",
  "tenant": "<tenant>",
  "certificate": "./cert.pfx",
  "folder": "./src",
  "library": "Shared Documents",
  "commandTimeout": 120000,
  "stateFile": ".bdoctor/state.json",
  "disableStatePersistence": false,
  "forceAll": false,
  "skipPrecheck": false,
  "applyTheme": false,
  "verbose": false,
  "timingDetails": false
}

Options which got added in a later version, like removeDeleted, work the same way. Point the $schema value to the version you are running to get autocompletion for them in your editor.

Info

The output option can be defined here as well, but it is best passed on the command execution (--output json). Setting it in the bdoctor.json file makes every local run report JSON instead of the readable task list.

Important

The flags which are marked with “This flag can only be added to the command execution” in the CLI options are the exception. These are ignored when you define them in the bdoctor.json file.

Important

The removeDeleted option removes pages from your site. It only runs when you confirm it, which means you still need to pass the --confirm flag on the command execution when you enabled it in the bdoctor.json file.

The next sections describe structured settings in bdoctor.json. Where a CLI override exists, such as --enableMath, its explicit value takes precedence.

Multilingual

bdoctor can be configured to automatically create multilingual pages. To accomplish this, you will need to configure the multilingual option in the bdoctor.json file with the following settings:

• multilingual: MultilingualSettings - Setting to specify if multilingual is enabled on the site and which languages are supported.
  • enableTranslations: boolean - Specifies if you want to enable or disable multilingual features on the site. Default: false.
  • languages: (string | number)[] - Locale names such as "nl-nl" or locale IDs (LCIDs) to enable on the site. Both forms can be mixed. See supported LCIDs in SharePoint.
  • overwriteTranslationsOnChange: boolean - Specify whether the changes made to user-specified text in the default language should automatically overwrite the existing translations made in all alternate languages.
  • translator: Translator - This property allows you to specify the Azure Translator Cognitive Service. When Specified, you allow bdoctor to use the translator APIs to machine translate your pages.

Manual translation example:

{
  "multilingual": {
    "enableTranslations": true,
    "languages": [
      1043
    ],
    "overwriteTranslationsOnChange": true,
    "translator": null
  }
}

Machine translation example:

{
  "multilingual": {
    "enableTranslations": true,
    "languages": [
      1043
    ],
    "overwriteTranslationsOnChange": true,
    "translator": {
      "key": "<subscription key>",
      "endpoint": "https://api.cognitive.microsofttranslator.com/",
      "region": "<region name, example: westeurope>"
    }
  }
}

Info

Check out the multilingual section to see how the pages themselves are linked to each other.

Site look and feel

If you want, you can define the site its look and feel. This needs to be done on global level in the bdoctor.json file.

• siteDesign: SiteDesign - Allows you to set the theme and header/footer chrome
  • logo: string - The path to your logo you want to use for the site, relative to the folder defined with -f, --folder (./src by default). The logo gets uploaded to a site folder in the library defined with --library. If the value is empty "" it will be used to unset the site its logo.
  • theme: string - The name of the theme to set
  • chrome: Chrome - Settings for the header/footer chrome
    • headerLayout: string - Specifies the header layout to set on the site. Options: Standard|Compact|Minimal|Extended.
    • headerEmphasis: string - Specifies the header its background color to set. Options: Lightest|Light|Dark|Darkest.
    • logoAlignment: string - When using the Extended header, you can set the logo its position. Otherwise this setting will be ignored. Options: Left|Center|Right.
    • footerLayout: string - Specifies the footer layout to set on the site. Options: Simple|Extended.
    • footerEmphasis: string - Specifies the footer its background color to set. Options: Lightest|Light|Dark|Darkest.
    • disableMegaMenu: boolean - Specify to disable the mega menu. This results in using the cascading navigation (classic experience).
    • hideTitleInHeader: boolean - Specify to hide the site title in the header.
    • disableFooter: boolean - Specify to disable the footer on the site.

Example:

{
  "siteDesign": {
    "logo": "./assets/bdoctor.png",
    "theme": "Red",
    "chrome": {
      "headerLayout": "Compact",
      "headerEmphasis": "Darkest",
      "disableMegaMenu": false,
      "disableFooter": false
    }
  }
}

Info

All properties you define in the siteDesign object are optional.

Important

The theme is only applied when you pass the --applyTheme flag to the publish command.

Markdown publishing settings

The markdown property configures the Better Doctor Markdown custom web part. Deploy its SPFx solution before publishing. Both rendering paths use this custom control, not SharePoint’s built-in Markdown control.

• markdown
  • allowHtml: boolean - Default: false. Enables author HTML and publish-time shortcodes. Better Doctor prepares HTML compatibility content for the web part when enabled; otherwise it sends prepared Markdown. Both paths sanitize rendered content.
  • theme: string - The code-block theme: Dark or Light (lowercase also accepted). Default: Dark. This does not set the SharePoint page/section theme.
  • shortcodesFolder: string - Specifies where custom shortcodes can be retrieved. Check shortcodes section to learn more about how shortcodes can be used. Default folder location Better Doctor expects is ./shortcodes. If you want to change this, you can use the shortcodesFolder property and update it appropriate.
  • tocLevels: number[] - Heading levels to include in the table of contents. Default: [1, 2, 3, 4].
  • extended: boolean - Renders the extended markdown syntax: emoji shortcodes, highlighted text, footnotes, definition lists and task lists. Default is true. Set this to false to only render the basic markdown syntax. Check the markdown syntax section to learn more.
  • enableMath: boolean - Default: false. Enables KaTeX for $...$ inline math and $$...$$ display math, independently of allowHtml. --enableMath true or --enableMath false overrides it; explicit false wins over a configured true.

Example:

{
  "markdown": {
    "allowHtml": true,
    "theme": "light",
    "shortcodesFolder": "./shortcodes",
    "tocLevels": [1, 2, 3, 4],
    "extended": true,
    "enableMath": false
  }
}

Important

The existing allowHtml gate for shortcodes and extended syntax is unchanged. Syntax highlighting/copy, fenced Mermaid, and opt-in math do not require it. Math expressions remain literal by default. Use the current 2.4.0.json schema for the markdown.enableMath property; its value is a JSON boolean, not a string.

Important

The repository remains authoritative. SharePoint’s Monaco preview offers temporary edits/export, not a save back to source or managed content. HTML compatibility content is read-only in that view. allowHtml does not permit scripts, event handlers, unsafe URLs, or arbitrary author CSS.

Reusable content partials

The partials property allows you to reuse markdown snippets on your pages. More information can be found on the partials page.

• partials
  • folder: string - Specifies where the partials can be retrieved. Default folder location Better Doctor expects is ./partials.
  • header: string - The partial which gets added at the top of every page.
  • footer: string - The partial which gets added at the bottom of every page.

Example:

{
  "partials": {
    "folder": "./partials",
    "header": "banner",
    "footer": "navigation"
  }
}

Info

Pages can skip the automatically added partials with the partials front matter property.

Global navigation structure

You can also define a static navigation structure in the bdoctor.json file. Example:

{
  "menu": {
    "QuickLaunch": {
      "items": [
        {
          "id": "documentation",
          "name": "Documentation",
          "url": ""
        }
      ]
    }
  }
}

The menu property can contain a QuickLaunch and/or TopNavigationBar elment with their corresponding static navigation links under the items property. More information about navigation items can be found in the menu section and on the navigation page.

Important

The menu property is what enables the navigation. When it is not defined in the bdoctor.json file, the page level menu front matter is ignored.

Important

If you specify arguments during command execution, they will be used instead of the values defined in the bdoctor.json file.