Getting Started

This section walks you through everything you need to get your first documentation site published on SharePoint with bdoctor.

Prerequisites

Before you can publish your first page, make sure the following is in place:

• Node.js 22.13.0 or higher on your machine or build agent.
• Permissions in your tenant to create an Azure Entra ID app registration, and an administrator who can grant admin consent to it.
• A SharePoint Online site where your documentation gets published. You pass its URL with the --url option, or store it in the bdoctor.json file.
• The matching Better Doctor Markdown SPFx solution, deployed and available to that site. Installing the CLI alone is not enough; follow the web part deployment and migration guide.

Install bdoctor

Install bdoctor globally. Pick the stable release, or the next release to try out the latest changes before they are published.

Stable

Using npm:

npm i -g @woznet/better-doctor

Using yarn:

yarn global add @woznet/better-doctor

Next

Using npm:

npm i -g @woznet/better-doctor@next

Using yarn:

yarn global add @woznet/better-doctor@next

Caution

Since v2.0.0, bdoctor no longer runs on older Node.js versions. If you are using bdoctor in a CI/CD pipeline, make sure the pipeline uses a supported Node.js version.

To quickly get started, we provided a sample repository which allows you to test out all the functionalities of Better Doctor.

Set up certificate authentication

bdoctor does not ship with an application of its own, so before you can publish anything you bring your own Azure Entra ID app registration and authenticate with its certificate:

1. Create an app registration in the Azure Portal.
2. Add the Sites.FullControl.All application permission from SharePoint, and grant admin consent for your tenant.
3. Generate a certificate, upload it to the app registration, and convert it to the PKCS format so you can pass it to bdoctor.

The certificate authentication section walks you through each of these steps with the required commands and screenshots.

Important

Certificate authentication is the only authentication type bdoctor supports. Without the Entra ID app registration and its certificate, bdoctor cannot sign in to your tenant.

Prepare the custom renderer

An authorized administrator must deploy the Better Doctor Markdown solution separately. It replaces the built-in Markdown control as the normal publishing target. Better Doctor checks availability before mutations in a page-publishing run, even if you pass --skipPrecheck.

Rollout gate

Deployed-browser validation and a tenant migration/rollback pilot have not been executed for this change. Complete the pilot checklist before wider rollout. Existing legacy controls need explicit --confirm for replacement; this is not an automatic app deployment or migration approval.

Publish your first pages

Once bdoctor, the custom renderer, and certificate authentication are in place:

1. Create the folder structure and the bdoctor.json file in your project:

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

2. Write your content as Markdown files in the source folder (./src by default). Check the pages section for the front matter each page supports.

3. Check what the next publishing run will do:

   bdoctor status

4. Publish your content to SharePoint:

   bdoctor publish --certificate ./cert.pfx

Info

The appId, tenant, and url values can live in the bdoctor.json file, so you only need to pass the certificate (and its password) on each run. Keep those secrets out of source control. More information can be found in the configuration section.

Keep authoring in your repository. The web part’s edit-mode preview/export does not save content back to source; HTML compatibility content is read-only there.

Next steps

• Content: write your pages, build the navigation, and reuse snippets with partials and shortcodes.
• CLI: all the commands bdoctor offers.
• Configuration: every command argument and bdoctor.json setting.
• CI/CD: publish your documentation automatically from Azure DevOps or GitHub Actions.