CLI

bdoctor is a command line tool. This section describes every command it offers. The arguments you can pass to these commands are documented in the CLI options section.

Command	What it does
bdoctor init	Creates the initial folder structure and the bdoctor.json file.
bdoctor publish	Publishes your Markdown files as pages on your SharePoint site.
bdoctor status	Shows what the next publish run will do, without changing anything.
bdoctor workflow	Generates a GitHub Actions workflow or Azure DevOps pipeline for your project.
bdoctor setup	Installs the <tab> autocomplete functionality.
bdoctor cleanup	Uninstalls the autocomplete functionality.
bdoctor version	Returns the installed version number.

Info

When you run bdoctor without any command, it asks you which command you want to execute.

Init

This command creates the initial folder structure for your documentation project (Check CLI options to see which arguments you can pass to the command).

Examples

Initialize a standard project:

bdoctor init

Initialize a project with the details of your app registration:

bdoctor init --url <url> --appId <appId> --tenant <tenant>

The command creates the following in the current folder:

• The source folder (./src by default, or the one you passed with -f, --folder).
• An index.md starter page in that folder, when it does not exist yet.
• A bdoctor.json file, when it does not exist yet, containing the $schema, auth, url, folder, overwriteImages, library, and webPartTitle values. The appId and tenant values are added when you passed them.

Important

bdoctor init never writes your certificate or its password to the bdoctor.json file, as these are secrets which are best kept out of source control. Pass them on each command execution, ideally from a secret in your CI/CD pipeline. Check the certificate authentication section for more information.

Info

Existing files are never overwritten, so it is safe to run bdoctor init again in an existing project.

Publish

The publish command starts the creation process of your static content in SharePoint. It will upload all referenced images and creates the navigation structure if provided (Check CLI options to see which arguments you can pass to the command).

Pages use the Better Doctor Markdown custom web part. The matching SPFx solution must already be deployed and available to the target site. Its availability is checked before cleanup, uploads, multilingual configuration, or page mutation in a page-publishing run, independently of --skipPrecheck. Better Doctor does not deploy the app or silently fall back to the built-in Markdown control.

Legacy replacement requires --confirm and an unambiguous component-ID/title match. --forceAll alone is not migration approval; --skipExistingPages leaves existing pages unmigrated. Read the deployment, migration, and pilot guide before upgrading a site.

Examples

When using a bdoctor.json file, you can just run the publishing command:

bdoctor publish

If you want to manually pass your arguments, you can do this as follows:

bdoctor publish --url https://<tenant>.sharepoint.com/sites/<documentation>

For an approved legacy migration on a pilot site:

bdoctor publish --confirm

To enable KaTeX math, use bdoctor publish --enableMath true. Explicit --enableMath false overrides a configured markdown.enableMath: true. Neither form changes the markdown.allowHtml setting.

Reporting the run to your pipeline

Pass --output json to get the result of the run as a single JSON document instead of the publishing stats. Check the JSON output section for the document it returns.

bdoctor publish --output json > publish.json

Status

The bdoctor status command is a read-only command which compares your local markdown files against the publish state stored in SharePoint. It tells you what the next bdoctor publish run will do, without making any changes to your site.

bdoctor status

Important

The command requires the --url option (either passed as an argument, or defined in the bdoctor.json file), as it needs to download the state file from your site.

The output groups your pages in the following categories:

• New: files which are not yet tracked in the state, and will be created.
• Modified: pages whose content or rendering fingerprint changed since the last publish.
• Deleted: pages which are tracked in the state, but no longer exist locally. Use the --removeDeleted flag on your next publishing run to recycle them.
• Unchanged: files which are up to date. These are only listed when you pass the --verbose flag.

At the end, you get a summary telling you how many pages will be published on the next run:

 ⚡ 4 pages will be published on next run

Info

When state persistence is disabled with --disableStatePersistence, no state gets loaded and all pages are reported as New.

Info

The status command always reports the real difference with the state. The forceAll option is ignored here, as it only influences what bdoctor publish reprocesses.

Gating a pipeline on the status

Pass --output json to get the same report as a single JSON document, which lets a pipeline decide whether it has anything to do, or turn the changed pages into a pull request comment:

bdoctor status --output json | jq -e '.summary.upToDate'

Check the JSON output section for the full document.

The fingerprint includes resolved partials, render options such as enableMath, shortcode implementations, and the renderer contract. Upgrading from old state can report a one-time modification without changing the Markdown file. This comparison does not prove deployed assets or migration behavior work in a browser.

Referenced .lang.md files are compared under their localized page identity; unreferenced language files are reported as Orphaned. Source pages without a resolvable title/slug cannot be safely mapped. Keep the same effective rendering options for status and publish.

Workflow

The bdoctor workflow command generates a CI/CD definition which publishes your documentation. It supports GitHub Actions and Azure DevOps.

bdoctor workflow

Provider

Use the --provider argument to pick the platform to generate the file for. When you leave it out, bdoctor generates a GitHub Actions workflow.

Provider	Aliases	Generated file
github	gh, github-actions, actions	.github/workflows/bdoctor.yml
azdo	ado, devops, azure-devops, azure-pipelines	azure-pipelines.yml

bdoctor workflow --provider azdo

GitHub Actions

The command creates the .github/workflows folder when it does not exist yet, and writes a bdoctor.yml workflow file in it. The workflow runs when you push a change to the main branch, and can be started manually via the workflow_dispatch trigger.

Add the required values as repository secrets before running the workflow.

Azure DevOps

The command writes an azure-pipelines.yml file in the root of your project. The pipeline runs when you push a change to the main branch, and pull request triggers are disabled.

Add the required values as secret pipeline variables, or add them to a variable group which you link to the pipeline. The pipeline maps them to environment variables in its publish step, as Azure DevOps does not pass secret variables to the pipeline environment on its own.

Secrets

The generated file only passes the arguments which are not known yet. When your bdoctor.json file already contains the url, appId, and tenant values, these are left out of the bdoctor publish command, as bdoctor picks them up from the config file itself.

Secret	Description
CERTIFICATE	The base64 encoded contents of your certificate (.pfx, .p12, or .pem).
CERTIFICATE_PASSWORD	The password of your certificate.
APP_ID	The client ID of your Entra ID app registration. Only needed when appId is not in your bdoctor.json file.
TENANT_ID	The ID of your tenant. Only needed when tenant is not in your bdoctor.json file.
SITE_URL	The URL of the SharePoint site to publish to. Only needed when url is not in your bdoctor.json file.

Info

An existing .github/workflows/bdoctor.yml or azure-pipelines.yml file is never overwritten. Delete or rename it when you want to generate a new one.

Important

The generated file is a starting point. Change the branch, the path filter, or the arguments of the bdoctor publish command to match the way you work.

Setup

The bdoctor setup command allows you to initialize the autocomplete functionality (<tab> completion) for bdoctor.

Example

bdoctor setup

When you now type, bdoctor <tab> you will get a list of available commands and/or related arguments.

Cleanup

The bdoctor cleanup command is there to uninstall the autocomplete functionality from bdoctor.

Important

You do not need to use it if you never ran the bdoctor setup command.

Version

This command returns the installed version number of the tool.

bdoctor version

Help

Running bdoctor with the --help argument shows the version you are running and the list of supported commands.

bdoctor --help