Validating content
bdoctor validate checks your Markdown files before they reach SharePoint: their front matter, the links and images they point to, and their tags. It reads only local files and, unless you turn it off, the external links. It never signs in, so it runs anywhere, including a pull request build.
bdoctor validateIt prints every problem it finds, grouped per file, and exits with code 1 when one of them is an error:
src/m365/setup.md 3 error The slug "M365/Setup.aspx" has to be lowercase. frontmatter/slug-lowercase 7 error "Office365" is an alias of "m365"; use the canonical tag. tags/alias 14 error The link "./Missing.md" points to a file that does not exist. links/file-not-found 18 warn The image "./img/flow.png" has no alt text. links/image-alt
Checked 409 files: 3 errors, 1 warning in 1 file.Each problem has a severity:
- error fails the run, and blocks a publish that requires validation.
- warn is reported, but does not fail the run.
- info is a note, such as a link that redirects. Notes are only counted; pass
--verboseto list them.
The rules live in the validation section of your bdoctor.json, so they change with your content rather than with Better Doctor. Without that section, only the checks every project needs run: parsable front matter with a title, well-formed unique slugs, and working links.
Running part of the checks
Section titled “Running part of the checks”| Option | What it does |
|---|---|
--only frontmatter,links,tags |
Runs only these checks. |
--file <path> |
Checks one file, such as a page you are about to add. Its slug is still compared with every page of the folder, and the file may lie outside it. |
--offline |
Skips the external links, which are the slowest checks. |
--strictExternal |
Reports every external link warning as an error, for a deliberate link audit. |
--fix |
Fixes what is safe to fix; see Fixing. |
--dryRun |
With --fix, reports what would change without writing. |
--output json |
Writes the report as one JSON document; see the JSON report. |
Front matter
Section titled “Front matter”| Check | Severity |
|---|---|
The file opens with a --- block that closes, and is valid YAML (line and column reported) of key: value pairs |
error |
Every field of requiredFields is there and not empty (default: title) |
error |
title, slug, layout and description are text; comments and draft are true or false; tags is a list of text |
error |
created is a date without a time (YYYY-MM-DD) and a real date, checked as written |
error |
The slug is lowercase, ends in .aspx, and has none of : ? * " < > | % # \ |
error |
| The slug is unique, compared with the slug publish derives for pages without one | error |
layout is one of layouts, when they are set |
error |
A hub’s index.md has menu.QuickLaunch with the hub’s id and a weight |
error |
| The slug starts with the hub folder the file lives in | warn |
A property is not one Better Doctor reads, nor in extraAllowedKeys; the closest known one is suggested |
warn |
| Two pages share a title | warn |
A hub is a top-level folder of your content whose name is the id of a menu.QuickLaunch item in bdoctor.json. The hub list is not repeated in the rules.
Translations take their slug and navigation from the page they translate, so they skip the required-field, slug and hub checks. A translation is a *.lang.md file; type: translation in the front matter of any other file only earns a warning, and the file is checked as a page. Publish and status skip such a page, so it is never published: remove the type, or rename the file.
Links are read the way the renderer reads them, so anything inside code is skipped, and a heading’s anchor is the id the page really gets: lowercase, spaces as hyphens, URL-encoded, and -1, -2 for repeated headings. ## Use the /statusline command is #use-the-%2Fstatusline-command.
| Check | Severity |
|---|---|
A relative link or image points to a file that exists. Links resolve by the same rule publish uses: URL-decoded, without the query and fragment, relative to the page, / from the content folder, a link without an extension as a .md page, and release-3.1 as release-3.1.md when that file exists |
error |
| The file name matches in case, as SharePoint and Linux do | error |
The target stays inside the content folder, and is not a path on one computer (C:\…, file://). An image, a header image and an image of an included partial are checked once symlinks are followed, as publish refuses to upload one outside (see images) |
error |
An anchor, on the page or on another page (page.md#heading), exists |
error |
An <include file="…" /> and the partials.header and partials.footer of bdoctor.json exist, inside the partials folder or the content folder once symlinks are followed (see where a partial may live). A file outside is reported without being read, whether it exists or not |
error |
A link with a space in it ([x](My Page.md)), which Markdown does not turn into a link |
error |
A reference link [text][ref] has its [ref]: url definition |
error |
[[wiki]] links and > [!NOTE] alerts, which SharePoint does not render; turn them off with links.forbidWikiLinks and links.forbidAlerts |
error |
mailto: and tel: links have the right shape |
error |
| An image has alt text | warn |
A linked .md file has a title or slug, so publish turns the link into a page link |
warn |
| A link points to a file that is neither a page nor an image, such as a PDF, which publish does not upload | warn |
A file of the content folder no page links to or shows, and a hub page no hub index links to (links.orphans) |
warn |
The partials the pages include, and the header and footer partials, are checked too, once each, as they end up on the page: their links resolve from the partial’s own folder, which is where publish points them. Anchors on the page itself and targets with a {{parameter}} in them are left out there, as they depend on the page.
links.hubIndexRows checks the table a hub’s index uses to list its pages. With { "linkText": "View Guide", "sourceColumn": 3 }, every row whose link text starts with View Guide has to point inside the hub, and its third column has to be filled in.
External links
Section titled “External links”http(s) links are requested, each URL once per run, a few at a time per host. Whether a failure is an error depends on how sure it is that the link is dead:
| Result | Severity |
|---|---|
| 404 Not Found, 410 Gone | error |
| The domain does not exist | error |
| A malformed URL | error |
| Timeout, connection refused or reset | warn |
| 401 or 403, from a sign-in page or a site that blocks automated requests | warn |
| 429 Too Many Requests | warn |
| 5xx server error | warn |
| A certificate problem | warn |
| A redirect loop, or too many redirects | warn |
| A redirect, with the final URL as the suggestion | info |
An http:// link that also works over https:// |
info |
| A link to a loopback, private or link-local address, which is not requested | info |
A 404 or 410 to a HEAD request is tried again with GET before it counts, as some servers answer HEAD wrongly. A failed DNS lookup is tried once more after a second.
The links come from your content, which in a pull request build is anyone’s content. So a link whose host is, or resolves to, a loopback, private, link-local or otherwise reserved address is never requested, and neither is a redirect to one; it is reported as a note. Set links.allowPrivateHosts to true to check intranet links from a machine you trust. The address is checked again when the connection is made, and the connection goes to the address that was checked, so a host that resolves to a public address first and to a private one a moment later is refused too.
Results that will not change by the next run are cached in .bdoctor/link-cache.json for 24 hours; set links.cacheFile and links.cacheHours to change that. The cache belongs to your machine: bdoctor init adds .bdoctor/ to your .gitignore, also when you run it again in an existing project, and a links.cacheFile outside that folder needs a line of its own. List known false positives, such as internal hosts or pages behind a sign-in, in links.ignoreHosts and links.ignoreUrls (a URL ending in * is a prefix).
Tags are checked against a vocabulary: a tags.json file in your project that maps each canonical tag to its label and the variants that mean the same thing.
{ "ai": { "label": "Artificial Intelligence", "aliases": ["artificial-intelligence", "genai"] }, "m365": { "label": "Microsoft 365", "aliases": ["microsoft-365", "o365", "office365"] }}Point to it with validation.tags.file. Tags are compared after normalizing them: trimmed, lowercase, spaces and underscores as hyphens, and no punctuation but hyphens. AI, Ai and ai are one tag, and so are Microsoft 365 and microsoft-365.
| Check | Severity |
|---|---|
| A tag is an alias; the canonical tag is suggested | error |
A tag is canonical but written differently, such as AI for ai |
error |
| A tag is not in the vocabulary; the closest tags are suggested | error |
| A tag repeats another one | error |
A tag is one of tags.provenance, which says where a page came from and belongs in a source property |
error |
A page has fewer than tags.min or more than tags.max tags |
error |
| The vocabulary itself is ambiguous: an alias claimed twice, or equal to another tag | error |
The tags.json that tags.file names is missing or is not valid JSON (tags/vocabulary, so a warn publish still goes on) |
error |
A page in a hub has no tag for its hub, with tags.hubDefaults |
warn |
bdoctor tags works on the tags alone:
| Command | What it does |
|---|---|
bdoctor tags check |
Runs the tag checks; exits 1 on an error. |
bdoctor tags report |
Counts every tag as written, and lists the ones used once and the canonical ones no page uses. Works without a vocabulary, to see how much cleanup there is before you write one. |
bdoctor tags suggest |
Proposes canonical tags for each unknown tag. It only proposes. |
bdoctor tags fix |
Rewrites aliases and differently written tags to the canonical tag. Unknown tags are left alone. Add --dryRun to see the changes first. |
bdoctor tags add <tag> |
Adds a tag to the vocabulary, or aliases and a label to one it has: bdoctor tags add m365 --alias o365 --label "Microsoft 365". |
Only tags add writes tags.json, and it refuses a change that would make the vocabulary ambiguous. Whether an unknown tag becomes an alias or a tag of its own stays your decision.
Fixing
Section titled “Fixing”bdoctor validate --fix fixes what needs no decision, then checks the result. It fixes only what the checks of the run cover, so --only links --fix changes nothing:
- Text values with spaces around them are trimmed.
- A required
commentsthat is missing becomestrue, and a requiredlayoutthe first oflayouts. - A
createdtimestamp becomes its date, written in quotes ("2026-01-31") so YAML reads it back as text. - With the tag checks on, tag aliases become their canonical tag, unless the vocabulary is ambiguous;
tags fixrefuses to run then.
It never makes up a slug or a title. Only the lines of the changed properties are rewritten: the order of the properties, their quotes, the line endings and the page itself stay as they were. A value written as a | or > block is left alone, and so is a property holding nested values; when a file’s fixes cannot be written, the report says so with a frontmatter/not-fixed warning. Run it with --dryRun first to see what it would change.
Filling in new required fields
Section titled “Filling in new required fields”Adding a field to requiredFields makes every existing page without it fail. List the field in backfillFields as well, and its errors are reported as warnings until you remove it from that list:
{ "validation": { "requiredFields": ["title", "slug", "layout", "comments", "description", "tags", "created"], "backfillFields": ["description", "tags", "created"] }}A --file run ignores backfillFields: a page you are about to add has to be complete.
Validating before every publish
Section titled “Validating before every publish”Set validation.beforePublish and bdoctor publish runs the front matter, tag and internal link checks before it signs in:
off(default): no checks.warn: problems are reported as one warning, and the publish goes on.block: an error stops the run before anything is published, listing the first 20.
External links are never checked here: they are too slow, and too often down for a moment, to hold a publish up. Run bdoctor validate on its own for them, for example on a schedule. --skipValidation skips the checks for one run.
The pipelines that bdoctor workflow generates run bdoctor validate --offline as a step of its own before the publish step, which stops the run on an error whatever beforePublish is set to.
The JSON report
Section titled “The JSON report”--output json writes the report as one document, which a pipeline can gate on or turn into a fix list. The exit code is 1 when success is false.
{ "command": "validate", "success": false, "version": "3.1.0", "folder": "src", "checks": ["frontmatter", "links", "tags"], "file": null, "summary": { "totalDocuments": 409, "failedDocuments": 1, "warningOnlyDocuments": 0, "passedDocuments": 408, "errors": 2, "warnings": 1, "infos": 0 }, "docs": [ { "file": "src/m365/setup.md", "status": "failed", "issues": [ { "check": "frontmatter/slug-lowercase", "severity": "error", "message": "The slug \"M365/Setup.aspx\" has to be lowercase.", "field": "slug", "line": 3, "suggestion": "m365/setup.aspx" } ] } ], "changes": [], "dryRun": false, "externalChecked": 120}docs lists only the files with something to report. Each issue has a stable check id, such as links/anchor, to key a fix list on.