Getting Started

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

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 site where your documentation gets published. You pass its URL with the --url option, or store it in the doctor.json file.

Install doctor

Install doctor 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 @estruyf/doctor

Using yarn:

yarn global add @estruyf/doctor

Next

Using npm:

npm i -g @estruyf/doctor@next

Using yarn:

yarn global add @estruyf/doctor@next

Caution

Since v2.0.0, doctor no longer runs on older Node.js versions. If you are using doctor 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 Doctor.

Set up certificate authentication

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

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 doctor supports. Without the Entra ID app registration and its certificate, doctor cannot sign in to your tenant.

Publish your first pages

Once doctor is installed and your app registration and certificate are in place:

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

   doctor 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:

   doctor status

4. Publish your content to SharePoint:

   doctor publish --certificate ./cert.pfx

Info

The appId, tenant, and url values can live in the doctor.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.

Next steps

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