Skip to content
- 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/2.4.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/2.4.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.
- 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
