Skip to content

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.

Terminal window
bdoctor validate

It 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 --verbose to 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.

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

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.

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 comments that is missing becomes true, and a required layout the first of layouts.
  • A created timestamp 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 fix refuses 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.

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.

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.

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