Skip to content

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).

Initialize a standard project:

Terminal window
bdoctor init

Initialize a project with the details of your app registration:

Terminal window
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.
  • A .gitignore file that ignores the .bdoctor/ folder, where bdoctor validate caches 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.md
Created bdoctor.json
Created .gitignore

When 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.

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.

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

Terminal window
bdoctor publish

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

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

For an approved legacy migration on a pilot site:

Terminal window
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.

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.

Terminal window
bdoctor publish --output json > publish.json

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.

Terminal window
bdoctor status

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.

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.

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:

Terminal window
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.

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.

Terminal window
bdoctor validate

It 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.

Check one page before you add it, compared with every page of the folder:

Terminal window
bdoctor validate --file "./drafts/My new page.md"

Check front matter and tags only, or everything but the external links:

Terminal window
bdoctor validate --only frontmatter,tags
bdoctor validate --offline

Fix what is safe to fix, after looking at what would change:

Terminal window
bdoctor validate --fix --dryRun
bdoctor validate --fix

Check 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.
Terminal window
bdoctor tags report
bdoctor tags add m365 --alias o365 --alias office365 --label "Microsoft 365"
bdoctor tags fix --dryRun

Only tags add changes the vocabulary. Check the tags section for the vocabulary format and the checks.

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

Terminal window
bdoctor workflow

The generated file installs Better Doctor, runs bdoctor validate --offline, and then runs bdoctor publish. Check validation before publishing for what the validate step does.

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
Terminal window
bdoctor workflow --provider azdo

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.

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.

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.

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.

bdoctor setup

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

autocomplete

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

This command returns the installed version number of the tool.

Terminal window
bdoctor version
BETTER DOCTOR v3.1.0

With --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.

Terminal window
bdoctor --help
bdoctor publish --help