Skip to content

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.

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/3.1.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.

The adminAppId, adminCertificate and adminPassword options of the optional admin app registration can be defined here too, next to appId. Like the regular certificate and its password, keep the certificate options out of a bdoctor.json file you commit, and pass them on the command execution instead.

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

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>"
}
}
}

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 a built-in SharePoint theme, or of a custom theme already registered in the tenant. See custom SharePoint theme.
    • 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
}
}
}

With a Sites.Selected app registration, the logo and the chrome settings are applied on the site itself and need nothing more. A custom tenant theme is applied through the tenant admin site, which needs the optional admin app registration; a built-in SharePoint theme does not.

A built-in SharePoint theme (Blue, Orange, Red, Purple, Green, Gray, Dark Yellow or Dark Blue) works by name as it is. A custom theme has to be registered in the tenant first: bdoctor applies a theme by name and never creates or updates one, so with --applyTheme a name the tenant does not know fails the run.

Custom SharePoint theme shows how to create the palette, register it in the tenant and apply it to the site.

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
}
}

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"
}
}

The validation property holds the rules bdoctor validate and bdoctor tags check your content against. Every property is optional; without the section only the checks every project needs run.

  • validation
    • beforePublish: string - off (default), warn or block. Whether bdoctor publish runs the front matter, tag and internal link checks before it signs in, and whether an error stops it.
    • exclude: string[] - Globs, relative to the content folder, of Markdown files that are never checked, such as **/*.assets/**.
    • requiredFields: string[] - Front matter properties every page must have, with a value. Default: ["title"].
    • backfillFields: string[] - Required fields whose errors are reported as warnings while existing pages are being filled in. Remove the list to make them blocking.
    • layouts: string[] - The allowed layout values. Empty allows any.
    • extraAllowedKeys: string[] - Front matter properties your project uses on top of the ones Better Doctor reads, such as tags and created. Other unknown properties are warned about.
    • hubs
      • slugPrefix: boolean - Default: true. Warn when a page’s slug does not start with its hub folder.
      • indexMenu: boolean - Default: true. Require a hub’s index.md to carry its menu.QuickLaunch id and weight.
    • tags
      • file: string - The tag vocabulary, relative to the current folder, for example ./tags.json.
      • min / max: number - The fewest and most tags a page may have.
      • provenance: string[] - Values that say where a page came from; they belong in a source property, not in tags.
      • hubDefaults: boolean - Default: false. Warn when a page in a hub has no tag for its hub.
    • links
      • external: boolean - Default: true. Check http(s) links.
      • allowPrivateHosts: boolean - Default: false. Also request links to loopback, private and link-local addresses, which are otherwise skipped so content cannot make a build probe its own network.
      • ignoreUrls / ignoreHosts: string[] - External URLs (a trailing * makes a prefix) and hosts that are never requested.
      • timeoutMs: number - Default: 10000. How long one external request may take.
      • concurrency / perHostConcurrency: number - Default: 8 and 2. How many external requests run at once, in all and per host.
      • cacheFile: string - Default: .bdoctor/link-cache.json. Where external results are cached.
      • cacheHours: number - Default: 24. How long a cached result is reused; 0 turns the cache off.
      • orphans: boolean - Default: true. Report files no page links to, and hub pages no hub index links to.
      • forbidWikiLinks / forbidAlerts: boolean - Default: true. Report [[wiki]] links and > [!NOTE] alerts.
      • hubIndexRows: object - linkText and sourceColumn of the rows of a hub index table, to check each row points into its hub and fills in that column.

A hub is a top-level folder whose name is the id of a menu.QuickLaunch item of the navigation below.

Example:

{
"validation": {
"beforePublish": "block",
"exclude": ["**/*.assets/**"],
"requiredFields": ["title", "slug", "layout", "comments", "description", "tags", "created"],
"backfillFields": ["description", "tags", "created"],
"layouts": ["Article"],
"extraAllowedKeys": ["tags", "created", "source"],
"tags": { "file": "./tags.json", "min": 1, "max": 6, "provenance": ["blog", "clippings"] },
"links": {
"ignoreHosts": ["intranet.contoso.com"],
"hubIndexRows": { "linkText": "View Guide", "sourceColumn": 3 }
}
}
}

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.