Skip to content
DoctorDoctor

Getting Started

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

Prerequisites

Section titled “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

Section titled “Install doctor”

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

Using npm:

Terminal window
npm i -g @estruyf/doctor

Using yarn:

Terminal window
yarn global add @estruyf/doctor

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

Set up certificate authentication

Section titled “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. To scope the app to a single site instead, use Sites.Selected and grant it rights on that site — see scoping the app to a single site. If your pages set managed metadata columns by their label, also add TermStore.Read.All from SharePoint.
  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.

Publish your first pages

Section titled “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:

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

    Terminal window
    doctor status --certificate ./cert.pfx

  4. Publish your content to SharePoint:

    Terminal window
    doctor publish --certificate ./cert.pfx

When the certificate has a password, doctor asks for it — the input shows as dots.

Publish from behind a proxy

Section titled “Publish from behind a proxy”

When your network only reaches Microsoft 365 through a proxy, set the standard proxy environment variables together with NODE_USE_ENV_PROXY=1:

Terminal window
export HTTPS_PROXY=http://proxy.contoso.com:8080
export HTTP_PROXY=http://proxy.contoso.com:8080
export NO_PROXY=localhost,.contoso.com
export NODE_USE_ENV_PROXY=1


doctor publish --certificate ./cert.pfx

doctor runs the CLI for Microsoft 365 it ships with, not the m365 command installed on your machine, and calls a few SharePoint APIs directly with Node.js. NODE_USE_ENV_PROXY=1 makes Node.js send both through the proxy, tunneling HTTPS requests the way most corporate proxies expect. Without it, those direct calls skip the proxy, and some proxies reject or redirect the requests the CLI for Microsoft 365 sends. Hosts in NO_PROXY are reached directly.

Next steps

Section titled “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.
Visitors