Options

Options are specified via command arguments, or within a doctor.json file (automatically gets created on initialization doctor init).

For all commands

-a, --auth <auth>: Specify the authentication type to use. Values can be deviceCode (default) or password or certificate.

--username <username>: When using password authentication, you need to pass the username and password.
--password <password>: When using password authentication, you need to pass the username and password.
-u, --url <url>: The URL of the site collection to use.
--library <library>: Specified the library which you want to use in SharePoint to store your referenced images.
-f, --folder <folder>: The folder location in where you will create your markdown files.
--webPartTitle <webPartTitle>: This defined the title of the markdown web part to be created/updated on the page. Default value is: doctor-placeholder.
--overwriteImages: Specifies if you allow doctor to overwrite the images in the SharePoint library that are referenced in the markdown files.
--debug: Provides more information of what is happening during command execution.

--continueOnError: Continue when an error occurs during the publishing process.
--disableTracking: In order to make doctor better, we need to know how it is used. That is why we started to track which commands and related parameters are used. We are not tracking the values of these parameters, only if they are used or not. Still if you want to opt-out, you can do this by specifying the disable tracking flag.

Publish command specific options

--outputFolder <outputFolder>: When providing this option, the processed markdown files will be generated in this folder.

--cleanEnd: Removes the pages which have not been touched during the publishing run. This will happen at the end of the whole process.

--cleanStart: Removes all pages before creation. This ensures that you that all changes made to your documentation get removed.

--confirm: Don’t prompt for confirming removing the files when you specified to clean up pages and assets before publishing.

--commandName <commandName>: In case you want to use the locally installed CLI for Microsoft 365, you can use this flag. By default, it uses the version specified in the doctor tool. You can use the a locally installed version as follows: --commandName m365.
--skipExistingPages: Will not overwrite pages if they already existed on the site.
--retryWhenFailed: Specifying this flag will retry the command if it failed. In some cases it can be that SharePoint failes to process your request, and this allows you to try again without running the whole flow from scratch.
--skipPages:: This flag allows you to skip the pages provisioning in the publish flow.

--skipNavigation:: This flag allows you to skip setting the navigation in the publish flow.

--skipSiteDesign:: This flag allows you to skip setting the site its look and feel in the publish flow.

--cleanQuickLaunch: Allows you to specify if you want to remove all the navigation elements defined in the QuickLaunch navigation before adding the new navigation structure.
--cleanTopNavigation: Allows you to specify if you want to remove all the navigation elements defined in the TopNavigation navigation before adding the new navigation structure.
--pageTemplate: Name of the default page template to use for all the pages which will be created.
--disableComments: Disable comments for all pages. By default the comments are enabled on the pages.

`doctor.json`

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

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

Multilingual

doctor can be configured to automatically create multilingual pages. To accomplish this, you will need to configure the multilingual option in the doctor.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: number[] - Locale IDs (or LCIDs) to enable on the site. An overview of the supported LCIDs for SharePoint can be found on Supported LCIDs by 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 doctor 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>"
    }
  } 
}

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 doctor.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. 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/doctor.png",
    "theme": "Red",
    "chrome": {
      "headerLayout": "Compact",
      "headerEmphasis": "Darkest",
      "disableMegaMenu": false,
      "footerEnabled": true
    }
  }
}

Markdown publishing settings

The markdown property allows you to define how you want to render the HTML in SharePoint. By default, Doctor lets the HTML being rendered by the Markdown web part. This property allows you to override these settings, and define to let Doctor take over for the HTML rendering.

markdown
- allowHtml: boolean - By default SharePoint renders the HTML. If you set this to true, it will allow Doctor to generate the HTML and allows you to make use of all HTML capabilities the tool has to offer. When you enable this, you can also make use of shortcodes in markdown to make more HTML rich pages.
- theme: string - Specify the theme to use for the code blocks. You can use Dark or Light. Default is Dark.
- shortcodesFolder: string - Specifies where custom shortcodes can be retrieved. Check shortcodes section to learn more about how shortcodes can be used. Default folder location Doctor expects is ./shortcodes. If you want to change this, you can use the shortcodesFolder property and update it appropriate.
- tocLevels: number - Specifies the number of levels to show in the table of contents. Default is [1, 2, 3, 4].

Example:

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

You can also define a static navigation structure in the doctor.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.

Markdown shortcodes

Shortcodes are HTML snippets inside your content files calling built-in or custom templates. You can use these shortcodes like custom HTML elements. Similar like custom web components. More information about these shortcodes can be found at our markdown shortcodes