Skip to content
- Changed: an image that stands alone in its paragraph or HTML block, a screenshot, gets a framed look on every site: centred, with a thin border, rounded corners and a soft shadow. It needs no markup and no option. Pages without
allowHtml are rendered by the web part, so they show it as soon as the updated Better Doctor Markdown solution is deployed, before any publish; pages with allowHtml pick it up on their next publish, since the renderer version moves to 2.1.0 and every page republishes once. An image in a sentence, a link, a table, a heading or a footnote, or one that opens a list item, is left alone, and with allowHtml an <img class="plain"> opts out.
- Added: web part styles that content-project shortcodes can rely on:
figure.bdoctor-screenshot with a centred figcaption, width classes bdoctor-w-5 to bdoctor-w-100 in steps of 5 and bdoctor-w-auto, <kbd> key caps (a nested <kbd> combo shows only the inner caps), .bdoctor-menu-path and details.bdoctor-collapse.
- Added:
bdoctor validate never requests a link to a loopback, private or link-local address, at any redirect, and checks the address again when it connects, so a name that answers a public address first and a private one a moment later is refused too, so content from a pull request cannot make a build probe its own network. validation.links.allowPrivateHosts turns that off for a trusted machine.
- Added:
bdoctor validate checks a content folder before it is published: front matter (valid YAML, required fields, types, a date-only created, lowercase .aspx slugs without forbidden characters, unique slugs and titles, allowed layouts, unknown properties, hub slugs and hub index navigation), internal links (missing files, case mismatches, anchors resolved with the renderer’s own heading ids, images and their alt text, includes, unencoded spaces, unresolved references, wiki links and alerts, orphaned files) and tags. It groups the problems per file and exits with code 1 on an error, also with --output json, which keeps the full report. --only, --file, --offline, --strictExternal and --verbose narrow or widen the run.
- Added: external link checks in
bdoctor validate. A 404, 410, unknown domain or malformed URL is an error; a timeout, 401/403, 429, 5xx, certificate problem or redirect loop is a warning; a redirect, or an http:// link that works over https, is a note. Each URL is requested once per run, a few at a time per host, and lasting results are cached in .bdoctor/link-cache.json for 24 hours.
- Added:
bdoctor tags check|report|suggest|fix|add checks tags against a tags.json vocabulary of canonical tags and their aliases, counts them, proposes canonical tags for unknown ones, rewrites aliases in place, and adds tags to the vocabulary. Only tags add writes the vocabulary.
- Added:
bdoctor validate --fix trims values, adds a missing required comments or layout, cuts a created timestamp to its date and replaces tag aliases, rewriting only the changed front matter lines. --dryRun shows the changes first.
- Added: a
validation section in bdoctor.json (and schema/3.1.0.json) for the rules: requiredFields, backfillFields to report fields still being filled in as warnings, layouts, extraAllowedKeys, exclude, and the hubs, tags and links settings. Hubs are the menu.QuickLaunch items of the navigation.
- Added:
validation.beforePublish set to warn or block makes bdoctor publish run the front matter, tag and internal link checks before it signs in, and block stops the run on an error. --skipValidation skips them for one run.
- Added: an optional admin app registration for the calls a
Sites.Selected grant cannot reach, set with --adminAppId, --adminCertificate and --adminPassword (or adminAppId, adminCertificate and adminPassword in bdoctor.json). bdoctor publish signs in as it only when a task needs the tenant admin site: applying a custom siteDesign.theme with --applyTheme, and setting siteDesign.logo when the site refuses the regular app. The regular publish keeps needing nothing more than its site grant.
- Added:
APP_CATALOG_SCOPE=tenant in scripts/deploy-webpart.js deploys the Better Doctor Markdown solution tenant-wide from the tenant app catalog, signed in as the admin app registration (ADMIN_APP_ID, ADMIN_CERTIFICATE_PATH or ADMIN_CERTIFICATE, ADMIN_CERT_PASSWORD). The default, sitecollection, is unchanged.
- Added:
bdoctor init adds .bdoctor/ to the project’s .gitignore, and creates the file when it is missing, so the external link cache of bdoctor validate stays out of source control. It never adds the line twice, keeps the file’s line endings, does the same when run again in an existing project, and lists the change in its output.
- Changed:
siteDesign.logo is set through the site’s own siteiconmanager API instead of m365 spo site set, which looked the site up through the tenant admin site first. A site granted with Sites.Selected now gets its logo without an admin app.
- Changed: a theme or logo skipped because the app has no permission is reported as a warning instead of only in the
--debug output. A custom theme the app may not apply is skipped rather than failing the publish when its name is no built-in SharePoint theme.
- Changed: the configuration schema is now
schema/3.1.0.json, which adds the three admin options and the validation section, and no longer suggests a pageTemplate default. bdoctor init writes its URL; an existing bdoctor.json keeps working against 3.0.0.json.
- Changed: the help and every command run start on the first line with a plain
BETTER DOCTOR v<version> heading, instead of a padded banner after a blank line, and the help no longer ends with a blank line. The general help drops its tagline and credit lines and ends at the documentation link; the credits moved to the readme.
- Changed:
bdoctor version prints only BETTER DOCTOR v<version>, without the job start, timing and completion lines around a second copy of the version. Its --output json document is unchanged.
- Changed: commands no longer print the
START, EXECUTION TIME and COMPLETED job lines around their output. publish and status keep the task checklist but no longer keep each task’s detail lines once it finishes (they still show with --verbose). The status report shows only the groups that have pages in them, without (none) placeholders. The publish summary drops its badge and shows images, removed pages and retries only when there are any. init lists what it created, workflow prints the created file, and setup and cleanup say what they change. The --output json documents are unchanged.
- Changed: replacing an image file republishes the pages that show it, even when their Markdown did not change, and
bdoctor status reports those pages as modified. The page fingerprint now covers the content of each local image a page shows, its header image included. The publish state records the content hash of every image bdoctor uploads, so a changed image replaces the copy in the asset library without --overwriteImages; an unchanged image that already exists is still kept. Pages with local images republish once after upgrading, and their images are uploaded again once.
- Changed:
bdoctor version and the help start in 0.1 s instead of 1.6 s on Linux, and in 0.24 s instead of 6.2 s on Windows, as they no longer load the commands, the prompt library, or the SharePoint and HTML libraries behind them. bdoctor version --output json returns the same document as before. The prompt library is loaded only when there is something to ask, such as an unconfirmed --cleanEnd. bdoctor init and bdoctor workflow no longer load the CLI for Microsoft 365 or the HTML sanitizer either (for init, 0.5 s instead of 1.6 s on Linux and 1.2 s instead of 6.1 s on Windows), and bdoctor status, which builds no page content, no longer loads the sanitizer (1.2 s instead of 1.6 s up to signing in). publish loads both before signing in and status the CLI, so a broken install still fails before anything is published.
- Changed: the light Better Doctor theme in the custom theme guide uses the darker teal
#117466 (5.7:1 on white) instead of #158274 (4.7:1), which fell below 4.5:1 for links on the tinted table header and inline code background and in sections with the Soft background. The guide also explains why a dark theme needs --isInverted when it is registered, notes that m365 spo theme set cannot register the 2.0.0 theme format, and names the newer SharePoint default themes, such as Teal, that siteDesign.theme cannot apply by name.
- Changed: the Better Doctor Markdown web part’s fallback link colours, used only when SharePoint supplies no theme, follow the new light theme:
#117466, and #0a4039 on hover.
- Changed: the pipelines
bdoctor workflow generates for GitHub Actions and Azure DevOps run bdoctor validate --offline before bdoctor publish, so content with an error fails the run before it signs in. The step needs no secrets, and leaves the external link checks out so a site that is down for a moment does not hold up a publish.
- Changed: an
<include file="…" />, and the partials.header and partials.footer of bdoctor.json, only read a file inside the partials folder or the content folder, once symlinks are followed. An absolute path, a ../ chain or a symlink that leads anywhere else fails the page in bdoctor publish, like a missing partial, and is a links/include error in bdoctor validate, which reports it without reading the file or saying whether it exists, so content from a pull request cannot put a file of the build machine on a page.
- Changed:
bdoctor publish no longer uploads an image that lies outside the content folder. An image in a page, in a partial, or in header.image that leaves the folder by ../, by an absolute path or through a symlink fails the page before anything is uploaded, and the pre-check reports it. bdoctor validate reports these as links/outside-folder, now following symlinks and covering header images and the images of partials. Images stored next to a partial outside the content folder are refused too; keep them in the content folder and point at them with a / path.
- Fixed: publish reads a link or image source the way the renderer writes it: URL-decoded, without its query and fragment, and
/ from the content folder. A link to My%20Page.md is now rewritten to its page however it is written, also as [x](<My Page.md>), with accented letters such as bild-ü.png, or in an <img> tag, page.md#section keeps its anchor, an image in a folder with a space in its name is uploaded and passes the pre-process check, and a local file whose name starts with http, such as http-flow.png, is no longer taken for a web address. bdoctor validate uses the same rule. The renderer fingerprint changes, so every page is published once more.
- Fixed: every command searched the whole working directory,
node_modules included, for machine translated pages to delete when it finished, which added close to a second to bdoctor version and would walk an entire home folder. The pages a publish writes are now removed by name, and only bdoctor publish still looks for the ones a crashed earlier run left behind, under its --folder and skipping node_modules and .git. A run that fails before its options are read, such as on a malformed bdoctor.json, no longer deletes anything, so a --debug run keeps its files there too.
- Fixed: every command,
bdoctor version included, deleted a temp folder in the working directory with everything in it, whoever had put it there. Better Doctor now removes only the files it wrote to temp, and the folder only once it is empty and was created by the run. bdoctor publish also removes the web part payloads (<uuid>.json) that an interrupted earlier run left in temp, and then the folder if they were all it held; a temp that links to another folder is never searched. Scratch files from a --debug run are now cleared by the next publish instead of by any command.
- Fixed:
--cleanEnd recycled a page the same run had just published when its slug had capitals in it (from a folder such as Getting-Started/, or a front-matter slug) and the page set no metadata or description. Such pages are now recognized as published, and those that do set metadata or a description no longer cost a second spo page get each.
- Fixed:
bdoctor publish and bdoctor status with --output json printed [STARTED] Authenticate to M365 with certificate to stdout ahead of the JSON document when the output was not a terminal, as in a CI/CD pipeline, so the document could not be parsed. The sign-in step is now silent with --output json, like the rest of the run.
- Fixed: a heading whose anchor is also the name of a page property, such as
## Links, ## Images, ## Title or ## Name, lost its anchor when the page was cleaned, so the table of contents and links to it went nowhere. These headings keep their anchor now, in the published page and in the web part.
- Fixed: the Better Doctor Markdown web part scrolls to the heading a link from another page points to (
page.aspx#setup), once the content has rendered and whenever the address changes. Before, the browser looked for the heading before the web part had drawn it, under an id the web part then renamed.
- Fixed: a Mermaid diagram and its source were marked as one image, which hid the source and any render error from screen readers. Only the drawn diagram is an image now, with its label, and the source can be opened beside it.
- Fixed: a link with any
target, not only _blank, opens without a reference back to the page (rel="noopener noreferrer"). The code copy button is named Copy code followed by the language, so a voice command for the visible text finds it.
- Fixed: exporting a draft when SharePoint leaves edit mode could cancel the download in some browsers, losing the draft.
- Fixed: the
publish summary counted an image again for every page and every spelling that showed it, and counted images it kept as uploaded; images.skipped in the JSON report was always 0.
- Fixed:
<include file="/navigation" /> is read from the content folder, as documented, instead of from the root of the disk. Only a Windows drive or network path is used as an absolute path, and it has to be inside the partials or content folder like any other include.
- Fixed: a sign-in error that repeated the certificate or its password showed every copy after the first in clear, because a value with characters such as
+, / or $, which every base64 certificate has, was only masked once. Every copy is masked now, for the regular and the admin app registration alike.
- Added: woznet/better-doctor-sample, the sample documentation project CI publishes against. It is the upstream sample renamed to
bdoctor and corrected for this fork: certificate-only authentication, the status command, the publish-state flags, the web part deployment prerequisite, and a new KaTeX math page. scripts/prepare-sample.js now reads bdoctor.sample.json from it.
- Changed: the configuration schema is now
schema/3.0.0.json, named after the release that changed it. It adds markdown.enableMath and moves the stateFile and webPartTitle defaults to .bdoctor/state.json and bdoctor-placeholder, so it is no longer the same document as the 2.1.0.json it was edited out of. It is served from https://cloud13.blob.core.windows.net/public/bdoctor/schema/3.0.0.json while this repository is private; bdoctor init writes that URL, and an existing bdoctor.json needs its $schema value updated by hand.
- Changed: the logo is redrawn (a Markdown card and the
BDoctor wordmark) and the docs site icons follow it. Sample-repository links now point at woznet/better-doctor-sample.
- Changed: the documentation site is served from
https://better-doctor.cwoz.dev/. Cloudflare Workers Builds builds docs/ on every push to main and publishes it as an assets-only Worker described by docs/wrangler.jsonc; the links in bdoctor --help, the sign-in guidance, the readme and the SPFx solution manifest all follow it. Node.js is pinned once in .node-version, which every GitHub workflow and the Cloudflare build read.
- Breaking: the content contract is now version 2.
managedBy is "bdoctor", the published markup uses data-bdoctor-* attributes and bdoctor-* classes, and schemaVersion, the web part data version and bdoctorContractVersion all moved to 2. Content published by an earlier release is rejected rather than half-rendered: redeploy the solution and run bdoctor publish once.
- Breaking: the configuration file is now
bdoctor.json. A doctor.json in the project root is still read as a fallback, and the new name wins when both exist.
- Breaking: the publish-state default moved to
.bdoctor/state.json. Pass --stateFile .doctor/state.json to keep an existing state file; otherwise the next publish treats every page as new, which the contract bump forces regardless.
- Breaking: the SPFx project is now
bdoctor-markdown-webpart/ and packages as bdoctor-markdown-webpart.sppkg, so deployment and CI paths change. The component, solution and toolbox GUIDs are unchanged, as is the built-in Markdown web part id that legacy migration matches on.
- Changed: the web part is titled Better Doctor Markdown in the SharePoint toolbox, and every message it renders now names Better Doctor.
- Changed:
bdoctor workflow writes bdoctor.yml. Pipelines already generated as doctor.yml keep their filename and keep working until regenerated.
- Changed: source identifiers follow the fork name (
BDoctor* types, BDOCTOR_* constants, the @bdoctor/markdown-core build alias, bin/bdoctor). Attribution, the generated changelogs and the deferred items in TODO.md are exempt, and tests/branding.test.mjs requires every remaining doctor to be listed with a reason.
- Removed:
src/styles/shortcodes.ts, an unused stylesheet left over from before the web part owned all rendering.
- Security:
markdown-it moves to 14.3.2 in both the CLI and the web part, closing a quadratic-complexity denial of service in the smartquotes rule (GHSA-6v5v-wf23-fmfq). The two pins have to move together because src/markdown/ is the parser core both sides compile against. The renderer version bump for the searchable-text fix below republishes every page once, so existing pages are rebuilt on the new parser too.
- Security: the web part’s
postcss build dependency moves to 8.5.28, closing an arbitrary source-map read through an attacker-controlled sourceMappingURL (GHSA-fxqj-rqcc-2cmp). Build-time only; nothing in the shipped solution changes.
- Security: the CLI for Microsoft 365 moves from 11.5.0 to 11.11.0, which clears 30 advisories carried by its vendored dependencies — four of the five criticals and fourteen of the highs, including
fast-xml-parser, swiper, adaptivecards, axios, minimatch, node-forge and lodash. Every command and option Better Doctor invokes is unchanged, so no configuration or pipeline needs editing.
- Fixed:
*.log is ignored, and the captured deploy log that had been committed is untracked. Its absolute build paths carried the pre-rename spelling of the product name, which failed the naming assertion in tests/branding.test.mjs for every checkout.
- Changed: the SPFx solution declares
config.solution.features instead of letting Heft generate one, which silences the features not set! packaging notice. The declared feature reuses the component GUID Heft already keyed the generated one off, so a tenant the solution is already deployed to keeps the same feature.
- Changed: the CLI, the web part and the SharePoint solution share one version, starting at 3.0.0 (solution and feature
3.0.0.0, up from 1.0.0.0). SharePoint only upgrades a deployed solution when its version rises, and every release ships both, so they now move together; tests/version-sync.test.mjs fails when they drift. The feature version is set explicitly, because Heft writes 1.0.0.0 for a feature without one rather than inheriting the solution’s.
- Removed:
src/styles/extended.ts, src/styles/hljs-dark.ts and src/styles/hljs-light.ts, the last unused stylesheets left over from before the web part owned all rendering. Nothing imported them and the folder goes with them.
- Security: the YAML parser behind front matter moves to
js-yaml 3.15.2, closing quadratic-complexity CPU exhaustion in merge-key and !!omap handling (GHSA-52cp-r559-cp3m, GHSA-5p4m-2wfm-xmqj, GHSA-2883-xcg3-v3hh, GHSA-h67p-54hq-rp68, up to CVSS 7.5). It arrived through gray-matter, so every published file’s front matter was parsed by it; a crafted block could hang a publish, which matters most for content repositories that accept pull requests. gray-matter already allowed the fixed version, so only the lockfile changed.
- Fixed: a page whose text contains angle brackets, such as
--title <title> in a table of CLI options, no longer corrupts itself on publish. The CLI for Microsoft 365 writes the page’s searchable text into the canvas HTML without escaping it, so SharePoint read <title> as a tag and swallowed the rest of the canvas. From then on the page could fail with Error reading JObject from JsonReader and be left checked out; milder cases silently lost words from search. Escaping the text is not enough, because setting a page’s title or description re-saves the canvas SharePoint returns decoded. The searchable text now drops <, > and & instead. The page content is unchanged, and search still finds the words around them. BDOCTOR_RENDERER_VERSION moves to 2.0.1, so the next bdoctor publish republishes every page once and repairs pages published before the fix. A page left checked out and unreadable by this has to be recycled first.
- Fixed: with
markdown.allowHtml on, empty HTML elements no longer swallow the content after them. Shortcodes are parsed as XML, which wrote <iframe …></iframe> back as <iframe …/> and <div></div> as <div/>. HTML reads neither as closed. An empty video embed erased everything below it on the page, an empty <a id="…"></a> anchor wrapped the next heading and duplicated its id, and an empty <div> or <span> enclosed the following content. An HTML-style <br> without a slash also printed a second line break. Empty elements now keep an explicit end tag, and void elements such as <br> and <img> keep their content outside them. Pages are republished by the renderer version change above.
- Removed: the callout shortcode’s
bgColor and fgColor attributes. Author styles are stripped before a page is published and again in the browser, so they never had an effect; the callout no longer emits them, and existing uses are ignored. A callout’s colours come from its type and the section theme.
- Fixed: right-to-left text renders right-to-left. Paragraphs, list items, headings and table cells without a
dir take their direction from their first strong character, so Arabic or Hebrew text is right-aligned with its punctuation in place. Authors can also set dir="rtl", "ltr" or "auto", which the sanitizer now keeps; other values are removed. Needs the updated web part.
- Fixed: accessibility. The
# permalink next to each heading is hidden from screen readers and is no longer a keyboard tab stop, so keyboard and screen-reader users stop landing on a focus stop that announces nothing. A Mermaid diagram in an inverted (dark) section now sits on the section background instead of a light code card; its arrows measured 1.41:1 against that card. A formula that fails to render inside a sentence now shows its error and TeX source inline instead of breaking the paragraph. Needs the updated web part.
- Security: the Markdown editor preview no longer bundles the DOMPurify copy Monaco vendors into its own source (3.4.8, covered by advisories capped at 3.4.12). A build-time module replacement points Monaco at the pinned
dompurify 3.4.14, and tests/artifact-report.mjs asserts that 3.4.8 is gone from the package. npm audit still lists the advisory, because it reads Monaco’s metadata rather than the bundle. Needs the updated web part.
- Fixed:
--cleanEnd removed every page that was skipped because it was unchanged. Only pages this run created or updated counted as touched, so a run with nothing to change removed the whole site while the publish state still listed every page as published, and later runs kept skipping them. Skipped pages now count as touched, and --cleanEnd recycles pages instead of deleting them permanently, so a mistake can be restored from the recycle bin. A site hit by this needs one run with --forceAll, or --cleanStart, to publish its pages again.
- Changed:
--retryWhenFailed no longer retries a command whose answer cannot change: a page or file that does not exist, or a folder or page that already exists. Better Doctor expects several of those in a normal run, such as looking up a page before creating it, and each one used to wait 5 seconds and fail again; the first CI publish of the sample spent 45 retries that way. Throttling, timeouts and network errors are still retried.
- Changed:
@woznet/better-doctor is published to GitHub Packages (npm.pkg.github.com) as a private package while the project is private, instead of to npmjs. Installing needs a classic GitHub token with the read:packages scope and the @woznet scope mapped to that registry; the getting started guide shows the one-time setup. bdoctor workflow generates pipelines that authenticate: GitHub Actions with the workflow’s own GITHUB_TOKEN (grant the repository read access in the package settings), Azure DevOps with a new GITHUB_PACKAGES_TOKEN secret variable.
- Changed: the package contains only the CLI:
bin/, dist/, the licence and third-party notices, the readme and the changelog. It used to include repository-only files such as agent instructions, pilot notes and templates, because .npmignore listed what to leave out instead of what to ship. A files allowlist replaces .npmignore.
- Added: help for every command.
bdoctor <command> --help (or -h) and bdoctor help <command> show the options a command reads, grouped, with their aliases, a one-line description, examples and a documentation link; bdoctor help and bdoctor --help list the commands. With --output json the help is a JSON document. Help no longer reads bdoctor.json or validates the other arguments, so it works in any folder. See the help page.
- Changed:
bdoctor without a command shows the help instead of asking which command to run, and an unknown command fails with exit code 1 instead of running nothing. The JSON help document’s commands is now a list of name and summary pairs rather than names.
- Fixed: an absolute
--folder works. It was joined onto the current folder, so C:\docs became <current folder>\C:\docs and the run stopped with The provided folder location doesn't exist. An absolute --outputFolder and markdown.shortcodesFolder had the same fault.
- Fixed: the pre-process checks report a local image a page references that does not exist, including images from partials and in language files. The run used to pass the checks and then fail on the upload, after the pages before it had already been published. A partial that cannot be resolved is reported there too.
- Changed: the page hash ignores line endings. The same Markdown checked out with CRLF (Windows with
core.autocrlf) and LF (a Linux runner) used to hash differently, so switching publishers republished every page. LF content keeps its hash; a page last published from a CRLF checkout republishes once.
- Fixed: a new page that another run creates at the same moment is no longer adopted. When SharePoint reports that the page already exists, the run stops instead of adding its own control to it, and it no longer moves an existing root page with the same file name into a folder: only an empty page left by an interrupted run is moved, and never over an existing target. Publishing to one site from two runners at once is still unsupported.
- Changed: the web part has passed a tenant pilot for new content: publishing guards, publish state, read-mode rendering, production assets under the tenant CSP, edit-mode preview, recovery from page version history and multilingual publishing. Migrating pages that use the built-in Markdown control, and recovering an interrupted migration, were not piloted; the deployment guide says what still has to run before migrating such a site.
- Breaking: the CLI command is now
bdoctor, and doctor is retired with no alias, so this package can be installed alongside @estruyf/doctor without either overwriting the other. The shell-completion helper is bdoctor_auto. Re-run npm link or reinstall globally after upgrading; doctor will no longer resolve.
- Breaking: the package is now
@woznet/better-doctor. Generated GitHub Actions and Azure DevOps pipelines install it and invoke bdoctor publish, so pipelines generated by an earlier version keep installing the old package until you re-run bdoctor workflow.
- Changed:
bdoctor init writes the $schema URL from this repository on the main branch. Existing doctor.json files keep resolving against the original repository; the fixed $id in schema/2.1.0.json no longer names a 2.0.0.json file that never existed.
- Changed: shell completion registers under
~/.bdoctor. A registration written by doctor setup before this release is not removed by bdoctor cleanup, which looks for the new marker — remove the doctor completion block from your shell profile and the ~/.doctor/ directory by hand if you had it.
- Changed: every internal identifier is deliberately unchanged —
doctor.json, .doctor/state.json, managedBy, the data-doctor-* attributes, published CSS classes and the web part component ID. Existing pages and publish state stay valid and no republish is needed. tests/branding.test.mjs enforces this.
- Removed: the npm version badges, the Twitter link and the third-party visitor-tracking pixel from the readme and the documentation site.
- Breaking: Doctor publishes to the custom Doctor Markdown SPFx 1.23.2 web part by default. Deploy the matching solution separately before publishing. Availability is checked before cleanup or page-publishing mutations;
--skipPrecheck does not bypass it.
- Breaking: replacing a legacy Markdown control requires
--confirm and an unambiguous component-ID/title match. Recovery data stays in the staged control’s properties.migrationBackup under the page’s permissions, alongside native page versions; it is not stored in the asset library.
- Migration requires a saved page version and no pre-existing checkout. Staged backups support resumption; automatic vertical-section legacy migration is blocked pending tenant validation. Serialize publishers per site: checkout and canvas comparisons are not atomic compare-and-swap, particularly for same-principal writers. Review and recover a retained checkout before retrying.
- New: the custom renderer provides syntax highlighting, source-code copy, and temporary Monaco preview/export. The repository remains authoritative; HTML compatibility content, including generated translations, is read-only in the browser inspector. Active scripts and arbitrary author styles are not supported.
- New: opt-in KaTeX math via
markdown.enableMath (default false) or --enableMath true|false. An explicit CLI false overrides a configured true; math is independent of markdown.allowHtml.
- Changed: publish/status fingerprints include render options and renderer inputs, so existing state can require a one-time update even when source text is unchanged. Added isolated
webpart:build and webpart:package scripts and a deployment/migration guide. Browser and tenant migration/rollback validation remain required pilot gates, not completed checks.
- Fix: the root clean task uses Node filesystem removal for
dist, so builds and tests no longer depend on an external rm command on Windows.
- New: every full release carries the matching
doctor-markdown-webpart.sppkg as a release asset, so deploying the renderer no longer requires building it from source.
- Changed: the CLI no longer installs
mermaid and svgdom. Nothing renders diagrams at publish time any more, which makes for a considerably smaller install.
- #206: Changed: Mermaid diagrams render in the Doctor Markdown web part’s browser runtime using bundled Mermaid, instead of relying on SharePoint’s renderer or publish-time SVG image uploads.
- Fix: the first block of a page is now parsed as markdown instead of being kept as HTML when
markdown.allowHtml is enabled.
- Fix: pages that were skipped as unchanged no longer disappear from the site navigation.
- Fix: the Azure Translator endpoint of your own resource (
<name>.cognitiveservices.azure.com) is now called on the right path, and a trailing slash on the endpoint no longer breaks the request.
- Fix: partials are injected into machine translated pages, so their header and footer end up on the translated page in the target language.
- Fix: secrets are kept out of the
--debug output by property name, which covers multilingual.translator.key and no longer mangles values which happen to contain a secret.
- The
multilingual.languages setting now takes the same locale names as the localization front matter, for example ["nl-nl", "fr-fr"]. LCIDs keep working and both styles can be mixed.
doctor status reports the localized pages, and the language files which no page refers to.
- New
--removeDeleted flag which recycles the pages whose markdown file got deleted from your sources. It uses the publish state to know which pages Doctor created, and needs to be confirmed with --confirm.
- #59: The
workflow command can now generate an Azure DevOps pipeline with the new --provider azdo argument. The default remains GitHub Actions.
- #119: New
markdown.extended setting to render emoji shortcodes, highlighted text, footnotes, definition lists and task lists. Enabled by default, and requires markdown.allowHtml.
- #198: New
partials setting to reuse markdown snippets on your pages. Include them where you need them with <include file="..." />, or let Doctor add them to every page with partials.header and partials.footer.
- #198: Partials take parameters. Pass them as attributes on the include tag, like
<include file="warning" product="Doctor" />, and use them in the partial with {{product}}. Their default values are set with the params front matter of the partial.
- #199: Fix: multilingual pages are published again. Translations are now handled in their own phase which runs after the normal pages, so a translation is no longer skipped when its source page was unchanged. Language files are picked up by their
.lang.md name, and a failing SharePoint or translator call reports why instead of passing silently.
- #202: New
--output json argument which silences the human output and writes the result of your doctor status or doctor publish run as a single JSON document to stdout, so a pipeline can gate on it or turn it into a pull request comment.
- Breaking: Doctor now requires Node.js 22.13.0 or higher.
- Full refactoring to support the latest version of the CLI for Microsoft 365.
- New
doctor status command to see which pages are new, modified, deleted, or unchanged before publishing.
- Publish state is stored on the site (
Shared Documents/.doctor/state.json by default) and saved after each page, so a failed run can resume where it left off.
- Breaking: unchanged pages are skipped by default. Use
--forceAll to reprocess all pages like in previous versions.
- Breaking: the
siteDesign.theme is no longer applied automatically. Use the new --applyTheme flag to apply it.
- Breaking: the
certificateBase64Encoded option is renamed to certificate, which accepts the path to your certificate file (.pfx, .p12, or .pem) as well as its base64 encoded contents.
- New pre-process validation which checks the markdown files for duplicate slugs, missing titles, broken localization references, and front matter parse errors before any SharePoint call is made. Can be skipped with
--skipPrecheck.
- New
--verbose flag for extended logging output, and --timingDetails to show per-page timing statistics after a publishing run.
- New
--disableStatePersistence and --stateFile options to disable or relocate the state file.
- New
--skipExisting alias for the --skipExistingPages option.
- New
--commandTimeout option to configure the timeout of each command execution, which defaults to 2 minutes.
- Page processing messages now show a
[x/total] progress counter and the total publishing time is always shown.
- Fix: navigation and link processing no longer fail on pages without a
title or slug in their front matter.
- #58: New
doctor workflow command which generates the .github/workflows/doctor.yml GitHub Actions workflow to publish your documentation.
- #104: New
mermaid shortcode to render Mermaid diagrams on your pages.
- #112: Progress, log, and error messages now show the file path relative to the current folder instead of only the file name, so pages that share a name (like
index.md) can be told apart. Failed pages are also listed by path in the publishing summary.
- #171: Breaking: certificate authentication is now the only supported authentication type. The
deviceCode type is removed, as it signs you in as a user which does not work for all the APIs Doctor calls, and the password type is removed as it is no longer supported by the CLI for Microsoft 365. The --appId, --tenant, and --certificate options are now required.
- #192: Fix: the site logo is now resolved relative to the configured folder instead of the current working directory.
- Updates to support Node.js >= 18
- #153: Added a new
tocLevels option to define the heading levels to include in the table of contents. Thanks to Bradley Goulding.
- #89: [Enhancement]: Use Cognitive Service Translation API connection for machine translations
- #90: [Enhancement]: Custom colors for callouts
- #82: [Enhancement]: Allow comments to be disabled at global level
- #83: [Enhancement]: New implementation of the retry logic
- #84: [BUG]: Issue with skipping pages and multilingual
- #85: [BUG]: Fix recording video bug in Cypress during tests
- #95: [Enhancement]: Add test results to the documentation to gain a better view on how they perform
- #75: [Enhancement]: Ability to define a default template in
doctor.json
- #76: [Enhancement]: Ability to place the table of contents at the
left or right side of the markdown
- #77: [Enhancement]: Add pages in alphabetical order to the navigation (when weight is not defined)
- #80: [Enhancement]: Add multilingual support on site and page level
- #78: [BUG] Fix for fetching all list items via the library title
- #4: [Enhancement]: Added
skipPages, skipNavigation, and skipSiteDesign flags
- #45: [Enhancement]: Table of contents shortcode added
- #63: [Enhancement]: Get to know how doctor is used
- #64: [Enhancement]: Post clean-up of removed/untouched pages
- #65: [Enhancement]: Add a delay in the retry mechanism
- #66: [Enhancement]: Autocomplete functionality added for commands and its arguments
- #70: [Enhancement]: Ability to specify to clean the
QuickLaunch and/or TopNavigation
- #71: [Enhancement]: Easier debugging with ability to attach the VSCode debugger
- #72: [Bug]: Fix for encoding characters in codeblocks + tests
- #5: Documentation site created getdoctor.io.
- #6: Enhancement to allow Doctor to generate the HTML instead of the Markdown Web Part.
- #50: Fix for skipping pages.
- #51: Enhancement making skipping pages faster without the need to check each page.
- #52: Enhancements to make it possible to change the look and feel of the site.
- #54: Enhancements to set the code editor theme for Markdown.
- #55: Enhancements to minify the CSS provided to the Markdown web part.
- #56: Enhancements to set the site its logo.
- #57: Fix for only retrieving the page its metadata so that encoding of the page its content would not lead to issues.
- #62: Enhancement to specify to retry the command execution if it failed.
- #3: Added metadata support for pages.
- #34: Add support for certificate authentication (provided by Gustavo Covas).
- #44: Enhancement: Be able to specify which version of CLI for Microsoft 365 you want to use.
- #47: Fix for issue with encoding
< and > in the markdown.
- #48: Enhancement: Masking the password and certificate Base64 string in the console.
- #49: Enhancement: Debug configuration for
vscode added to the project.
- #33: Page template support added.
- #36: Enhancement: Added
--skipExistingPages support.
- #37: Fix issue with encoding special characters.
- #38: Enhancement: Added
--continueOnError support.
- #39: Fix for navigation command execution.
- #40: Fix issue with multiple images on pages.
- #41: Fix issue with 2nd level navigation items.
- #17: Enhancement: Add support for page description.
- #18: Enhancement: Support for setting header image of the page.
- #20: Enhancement: Add support for title area layout.
- #25: Make
draft optional.
- #26: Include folder name for slug when not set in front matter.
- #27: Add support in Front Matter to enable or disable page comments. By default they are disabled.
- #32: Added MIT license to the project.
- #7: Added parameter to clean up all pages and assets before publishing.
- #19: Added support for specifying the
layoutType from within the front matter.
- #21: Implemented easier command execution from within the tool.
- #22: Enhanced the test actions with screenshots.
- #23: Added process exit codes to make sure it correctly outputs a success or failure status.
- #16: Fix for specified webPartData is not a valid JSON string.
- Updated the CLI for Microsoft 365 to 3.4.0 as this has huge performance improvements
- #9: Removed the
jq dependency with a fallback to JSON parsing in the tool itself.
- #11: Unknown arguments do not blow up the command execution +
--help added to the main command.
- #12: Added cross-platform support.
- #14: Cross-platform builds and publishing setup on GitHub Actions.
- Added
outputFolder argument which when provided, will ouput the processed Markdown files with updated image and page links.
- #2: Added support for linking pages in Markdown.
- #1: Fix for when
m365 tool is not globally available