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 validate |
Checks front matter, links and tags before you publish. |
bdoctor tags |
Checks, reports on and fixes tags against your tag vocabulary. |
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. |
bdoctor help |
Shows the commands, or the options and examples of one command. |
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
Section titled “Examples”Initialize a standard project:
bdoctor initInitialize 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 (
./srcby default, or the one you passed with-f, --folder). - An
index.mdstarter page in that folder, when it does not exist yet. - A
bdoctor.jsonfile, when it does not exist yet, containing the$schema,auth,url,folder,overwriteImages,library, andwebPartTitlevalues. TheappIdandtenantvalues are added when you passed them. - A
.gitignorefile that ignores the.bdoctor/folder, wherebdoctor validatecaches its external link results for your machine. When the project already has a.gitignore,.bdoctor/is added at its end, unless a line already ignores the folder.
It lists what it created:
BETTER DOCTOR v3.1.0
Created src/Created src/index.mdCreated bdoctor.jsonCreated .gitignoreWhen the project already has a .gitignore, the last line reads Added .bdoctor/ to .gitignore instead, or is left out when the file already ignores the folder.
Publish
Section titled “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
Section titled “Examples”When using a bdoctor.json file, you can just run the publishing command:
bdoctor publishIf 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 --confirmTo 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
Section titled “Reporting the run to your pipeline”Pass --output json to get the result of the run as a single JSON document instead of the summary it prints at the end. Check the JSON output section for the document it returns.
bdoctor publish --output json > publish.jsonStatus
Section titled “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 statusThe 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
--removeDeletedflag on your next publishing run to recycle them. - Unchanged: files which are up to date. These are only listed when you pass the
--verboseflag.
The report lists only the groups that have pages in them, and ends with what the next publish will do:
Compared 16 local files with 14 tracked pages.
New (2) src/new-page.md src/other.md
Unchanged (14), pass --verbose to list
2 pages will be published on the next run.When nothing changed, the last line reads Everything is up to date.
Gating a pipeline on the status
Section titled “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.
Validate
Section titled “Validate”The bdoctor validate command checks your Markdown files before you publish them: their front matter, the links and images they point to, and their tags, against the rules in the validation section of your bdoctor.json. It reads only local files and the external links, never your site, so it needs no sign-in.
bdoctor validateIt lists every problem per file, and exits with code 1 when one of them is an error, so a pipeline step fails on it:
src/m365/setup.md 3 error The slug "M365/Setup.aspx" has to be lowercase. frontmatter/slug-lowercase 14 error The link "./Missing.md" points to a file that does not exist. links/file-not-found
Checked 409 files: 2 errors in 1 file.Examples
Section titled “Examples”Check one page before you add it, compared with every page of the folder:
bdoctor validate --file "./drafts/My new page.md"Check front matter and tags only, or everything but the external links:
bdoctor validate --only frontmatter,tagsbdoctor validate --offlineFix what is safe to fix, after looking at what would change:
bdoctor validate --fix --dryRunbdoctor validate --fixCheck the validating content page for every check, the rules, the JSON report, and how to make bdoctor publish run the checks first.
The bdoctor tags command works on the tags of your pages, against the tag vocabulary validation.tags.file points to:
| Mode | What it does |
|---|---|
bdoctor tags check |
Fails on any tag that is not canonical. The default mode. |
bdoctor tags report |
Counts each tag, and lists the ones used once and the ones no page uses. Works without a vocabulary. |
bdoctor tags suggest |
Proposes canonical tags for the unknown ones. |
bdoctor tags fix |
Rewrites aliases to their canonical tag. Add --dryRun to see the changes first. |
bdoctor tags add <tag> |
Adds a tag, or aliases and a label to one, to the vocabulary. |
Examples
Section titled “Examples”bdoctor tags reportbdoctor tags add m365 --alias o365 --alias office365 --label "Microsoft 365"bdoctor tags fix --dryRunOnly tags add changes the vocabulary. Check the tags section for the vocabulary format and the checks.
Workflow
Section titled “Workflow”The bdoctor workflow command generates a CI/CD definition which validates and publishes your documentation. It supports GitHub Actions and Azure DevOps.
bdoctor workflowThe generated file installs Better Doctor, runs bdoctor validate --offline, and then runs bdoctor publish. Check validation before publishing for what the validate step does.
Provider
Section titled “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 azdoGitHub Actions
Section titled “GitHub Actions”The command creates the .github/workflows folder when it does not exist yet, and writes a bdoctor.yml workflow file in it. It prints Created .github/workflows/bdoctor.yml followed by the secrets to add, and leaves an existing file untouched. 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.
The workflow installs Better Doctor from GitHub Packages with its own GITHUB_TOKEN and packages: read permission. That token can read the private package only after you give your repository access: in the better-doctor package settings, under Manage Actions access, add the repository with the Read role.
Azure DevOps
Section titled “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.
Validation before publishing
Section titled “Validation before publishing”Both generated files run bdoctor validate --offline as a step of its own, right before the publish step. It checks the front matter, the internal links and images, and the tags against the validation rules of your bdoctor.json, and exits with code 1 on an error. A page with a broken link or an invalid slug fails the run there, before the publish step signs in to your site.
The step reads only your files, so it needs none of the secrets. --offline leaves out the external link checks, as a site that is down for a moment should not hold up a publish. Run bdoctor validate without --offline on your own machine, or in a scheduled pipeline, to check those too.
Secrets
Section titled “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. |
GITHUB_PACKAGES_TOKEN |
Azure DevOps only. A classic GitHub personal access token with the read:packages scope, from an account that can read the private @woznet/better-doctor package. The pipeline uses it to install Better Doctor, and never passes it to bdoctor publish. GitHub Actions uses its own GITHUB_TOKEN instead. |
The bdoctor setup command allows you to initialize the autocomplete functionality (<tab> completion) for bdoctor.
Example
Section titled “Example”bdoctor setupWhen you now type, bdoctor <tab> you will get a list of available commands and/or related arguments.

Cleanup
Section titled “Cleanup”The bdoctor cleanup command is there to uninstall the autocomplete functionality from bdoctor.
Version
Section titled “Version”This command returns the installed version number of the tool.
bdoctor versionBETTER DOCTOR v3.1.0With --output json it writes a JSON document with command, success and version instead.
bdoctor help lists every command, and bdoctor <command> --help (or bdoctor help <command>) shows the options and examples of one command. Running bdoctor without a command shows the help too. Check the help page for every form and its JSON output.
bdoctor --helpbdoctor publish --help