Shortcodes and partials in practice
The shortcodes and partials pages describe each feature on its own. This page is about using them together on a real set of Markdown docs: which one to reach for, how a page is processed, a set of recipes you can copy, and the mistakes that are easy to make.
Which one to reach for
Section titled “Which one to reach for”| Partial | Shortcode | |
|---|---|---|
| What it is | A Markdown file whose content gets pasted into a page | A tag that a JavaScript function turns into HTML or Markdown |
| Reuses | The same content: text, links, images, even shortcodes | The same structure, with different content each time |
| Written in | Markdown, in ./partials |
JavaScript, in ./shortcodes (or a built-in) |
| Variations | {{params}} with defaults in front matter |
Attributes and the content between the tags |
Needs allowHtml |
No | Yes, markdown.allowHtml: true |
| A change republishes | Only the pages that use the partial | Every page (see what a change costs) |
A rule of thumb: when you copy and paste the same words onto several pages, make a partial. When you write the same HTML structure around different words, make a shortcode. When you do both — the same callout with the same wording on many pages — make a partial that uses a shortcode.
How a page is processed
Section titled “How a page is processed”Knowing the order explains almost every surprise:
- Partials are expanded. Every
<include />is replaced by its partial, parameters are filled in, and the partial’s links are rewritten to work from the page. Nested includes are expanded the same way. - The header and footer partials are added at the top and bottom, unless the page opts out.
- Shortcodes that run before Markdown are rendered: the built-in
tocandmermaid, and custom shortcodes withbeforeMarkdown: true. - The Markdown is converted to HTML.
- Shortcodes that run after Markdown are rendered: the built-in
calloutandicon, and custom shortcodes by default. - The HTML is sanitized and published to the Better Doctor Markdown web part.
This order has three consequences you can build on:
- A partial can contain shortcodes, because partials are expanded before any shortcode runs.
- A partial parameter can fill in a shortcode attribute:
<callout title="{{title}}">works. - A shortcode cannot output an
<include />tag, because partials have already been expanded by then.
Fenced and inline code is left alone at every step, so you can document <include /> tags and shortcodes on your pages by putting them in a code block.
A starter layout
Section titled “A starter layout”.├── bdoctor.json├── partials/│ ├── header.md│ ├── footer.md│ ├── contact.md│ ├── prerequisites.md│ ├── sign-in.md│ ├── callouts/│ │ └── deprecated.md│ └── diagrams/│ └── architecture.md├── shortcodes/│ ├── collapse.js│ ├── keys.js│ └── work-item.js└── src/ ├── home.md ├── guides/ │ └── install.md └── support/ └── contact.md{ "folder": "./src", "markdown": { "allowHtml": true, "shortcodesFolder": "./shortcodes" }, "partials": { "folder": "./partials", "header": "header", "footer": "footer" }}Keep partials/ and shortcodes/ next to src/, not inside it. The recipes below use this layout.
Recipes
Section titled “Recipes”An “On this page” table of contents on every page
Section titled “An “On this page” table of contents on every page”Put the toc shortcode in the header partial and every page gets a sticky table of contents:
<toc title="On this page" position="right" />Pages where it makes no sense, like a landing page, opt out in their front matter:
---title: Homepartials: header: false---Use partials: false to drop both the header and the footer.
A footer with an owner and a review date
Section titled “A footer with an owner and a review date”The footer partial nests a smaller contact partial and passes one of its own parameters on to it:
---params: owner: the Docs team reviewed: September 2026---
<include file="contact" team="{{owner}}" />
_Last reviewed: {{reviewed}}_---params: team: the Docs team---
**Questions or corrections?** Contact {{team}} through the [support page](/support/contact)./support/contact starts at the sources folder, so it resolves correctly from every page: ../support/contact from src/guides/install.md, ./contact from src/support/contact.md.
The footer uses bold text rather than a ## heading on purpose. A heading would show up in every page’s table of contents.
A reusable callout with parameters
Section titled “A reusable callout with parameters”A partial that wraps the callout shortcode keeps the wording of a recurring warning in one place:
---params: replacement: the new process---
<callout type="caution" title="Deprecated since {{version}}">
This feature is deprecated. Use [{{replacement}}]({{link}}) instead.
</callout><include file="callouts/deprecated" version="3.0" link="/guides/new-install" replacement="the new installer" />version and link have no default, so leaving either one off fails the publish with a message that names the missing parameter and the page. This is useful: a callout cannot go out with a hole in it.
A shared procedure
Section titled “A shared procedure”Steps that recur across how-to guides, like signing in, belong in a partial. They can use shortcodes too:
---params: site: https://contoso.sharepoint.com/sites/docs---
1. Open [{{site}}]({{site}}) in your browser.2. Sign in with your work account.3. Press <keys combo="Ctrl+K" /> to search the site.## Sign in
<include file="sign-in" />External links like {{site}} are never rewritten. <keys> is the custom shortcode from keyboard shortcuts below.
A shared diagram
Section titled “A shared diagram”An architecture diagram that appears on several pages is a partial with a Mermaid fence in it:
```mermaidflowchart LR A[Repository] --> B[bdoctor publish] --> C[SharePoint]```<include file="diagrams/architecture" />A fence works without allowHtml and doesn’t need < written as <, unlike the <mermaid> shortcode. Change the diagram once and every page that shows it republishes.
Custom shortcodes
Section titled “Custom shortcodes”A custom shortcode is a .js file in the shortcodes folder that exports a name, a render(attributes, html) function and an optional beforeMarkdown flag. The shortcodes overview covers the module formats. The three below cover the common cases.
Keyboard shortcuts
Section titled “Keyboard shortcuts”Attributes in, HTML out:
const escape = (value = "") => String(value) .replace(/&/g, "&") .replace(/</g, "<") .replace(/>/g, ">") .replace(/"/g, """);
// Usage: <keys combo="Ctrl+Shift+P" />export default { name: "keys", render: (attributes) => String(attributes.combo || "") .split("+") .map((key) => `<kbd>${escape(key.trim())}</kbd>`) .join("+"),};Press <keys combo="Ctrl+Shift+P" /> becomes Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>. Escape attribute values before you put them in HTML. Whoever writes the page controls them.
A collapsible section
Section titled “A collapsible section”Wraps the content between the tags:
const escape = (value = "") => String(value) .replace(/&/g, "&") .replace(/</g, "<") .replace(/>/g, ">") .replace(/"/g, """);
// Usage: <collapse summary="Show details"> Markdown content </collapse>export default { name: "collapse", render: (attributes, html) => `<details><summary>${escape(attributes.summary || "Details")}</summary>${html}</details>`,};<collapse summary="Troubleshooting">
- Check that you are signed in.- Clear the browser cache and try again.
</collapse>This shortcode runs after Markdown, so html is the content between the tags, already converted to HTML. The blank lines around that content matter. See Markdown inside a shortcode.
A link to a work item
Section titled “A link to a work item”Returns Markdown instead of HTML, so it has to run before Markdown is converted:
// Usage: <work-item id="1234" />export default { name: "work-item", render: (attributes) => { const id = String(attributes.id || "").replace(/\D/g, ""); return `[Work item ${id}](https://dev.azure.com/contoso/docs/_workitems/edit/${id})`; }, beforeMarkdown: true,};Fixed in <work-item id="1234" />. becomes a regular link. Use beforeMarkdown: true whenever a shortcode returns Markdown, and leave it off when it returns HTML.
Partials and shortcodes together
Section titled “Partials and shortcodes together”A partial can supply the wording and pass it into your own shortcode, just like it does with a built-in one:
---params: product: Contoso CLI version: "2.0"---
<collapse summary="Prerequisites for {{product}}">
- {{product}} {{version}} or later- Access to the [docs site](/home)
</collapse><include file="prerequisites" />
<include file="prerequisites" product="Contoso Sync" version="1.4" />Quote parameter defaults like "2.0" in front matter. Unquoted YAML turns 2.0 into the number 2.
Translated pages
Section titled “Translated pages”A .lang.md translation is a page of its own, so it gets the header and footer and can opt out of them. To show a footer in the page’s language, turn off the automatic one and include a translated partial:
---title: Installerenpartials: footer: false---
...
<include file="footer.nl" />A machine-translated page gets the partials of its source page, translated along with the rest of the content.
Pitfalls
Section titled “Pitfalls”Markdown inside a shortcode
Section titled “Markdown inside a shortcode”Put a blank line after the opening tag and another before the closing tag whenever the content between them is Markdown that spans more than one line:
<callout type="tip">
Use **bold** and [links](/home) freely here.
</callout>Without the blank lines, the whole block is treated as raw HTML and the Markdown inside it is published as-is, literal ** and [text](link) included. Content on a single line, like <callout type="tip">Short **tip**</callout>, is fine.
What a shortcode may output
Section titled “What a shortcode may output”Shortcode output goes through the same sanitizer as the rest of the page:
- Output containing
<script>,<style>,<iframe>,<object>,<embed>,<form>, anon…event attribute, astyleattribute or ajavascript:link fails the publish. - Other elements the web part doesn’t allow, like
<button>, are silently removed and only their text is kept. Stick to plain content elements: headings, paragraphs, lists, tables, links, images,<details>/<summary>,<kbd>,<mark>,<span>/<div>and simple inline SVG. - There is no custom CSS. A shortcode can set a
class, but only the classes the web part ships with are styled, likecallout callout-tip.
Name custom shortcodes with lowercase, hyphenated names that aren’t real HTML elements, like work-item rather than details. Every tag with that name is handed to your shortcode, real HTML elements included.
What a change costs
Section titled “What a change costs”- Changing a partial republishes only the pages that use it.
- Changing any file in the shortcodes folder, or a
markdownsetting, republishes every page, because it can change how any page renders.
Run bdoctor status to see which pages a change marks as modified before you publish.
Other things to know
Section titled “Other things to know”- Custom shortcodes run during
bdoctor publishonly. The web part’s edit-mode preview shows their published output but cannot run them again. - A partial that includes itself, directly or through other partials, fails the publish, as does nesting more than 10 levels deep.
- Write
\{{name}}to show a literal{{name}}in a partial without it being treated as a parameter. - Partials stored inside the sources folder are excluded from publishing, but keeping them outside it is clearer.