Summary
Add a consistent inline <span class="badge badge--primary">Pro</span> marker after section headings that describe Pro-only functionality, so readers get a fast visual cue without having to scan for an admonition block.
The pattern was used briefly in the v1.9 docs refresh and we liked it as a visual cue. Time to roll it out everywhere.
Why
We already mark Pro features two ways today:
- Pro Feature admonition (
:::info Pro Feature …) — full callout, used at the top of Pro-only pages like customers/index.mdx, orders/index.mdx, coupons/index.mdx. Good for context, but a bit heavy for a sub-section on a mostly-free page.
- Inline text ("requires Pro", "with Pro you can…") — easy to miss when skimming.
The inline badge fills the gap between the two: tight enough to sit at the end of an ## Heading, loud enough to be unmissable. No custom CSS needed — badge badge--primary is a built-in Infima class shipped with Docusaurus.
Visual
```mdx
Coupon Codes Pro
```
Renders as: a small blue pill saying "Pro" at the end of the heading.
Scope — pages to apply the badge
Anywhere a sub-section on a page documents Pro-only behaviour. Suggested first pass (not exhaustive — anything new follows the same rule):
Pages that mix free and Pro content
These have free sections plus Pro sections — the inline badge belongs on the Pro headings:
- `products/index.mdx` — heading for the inline COGS editing section (already has a Pro admonition at L98; the heading itself should carry the badge)
- `payment/index.mdx` — heading for the additional gateways section
- `pos/checkout/index.mdx` — headings for additional gateways and the coupon-application section
- `settings/wp-admin/store-tax-ids.mdx` — heading for the per-store tax ID section
- `pos/cart/discounts.mdx` — any heading that links into the coupons workflow (currently links out to `/coupons` — could also badge the comparison table row label if we want)
- `getting-started/index.mdx` — the `## Pro Features` section heading (current at L130)
- `templates/index.mdx` — the `## Pro Features` section heading (current at L58)
Whole-page Pro features
Pages that are entirely Pro (already carry a `:::info Pro Feature` admonition near the top) — adding the badge to the page `# Title` would be redundant and ugly. Leave the title alone, keep the admonition, but use inline badges if any sub-section on that page documents a Pro-only sub-capability that goes beyond the page's headline scope.
Pages in this bucket:
- `customers/index.mdx`, `orders/index.mdx`, `reports/index.mdx`, `stores/index.mdx`, `coupons/index.mdx`, `extensions/index.mdx` — keep the existing admonition, don't double-mark the page title.
When to use the badge vs the admonition
| Situation |
Use |
| Whole page is Pro |
:::info Pro Feature near the top, no inline badge on the title |
| Sub-section on a mixed page documents a Pro-only capability |
Inline badge on the heading, no admonition (unless the section needs an explanatory note) |
| Sub-section needs both a visual cue and clarifying text |
Inline badge on the heading plus a short :::note or :::info block with the detail |
Acceptance criteria
Out of scope
- Designing a new colour or variant for the badge — we're using Docusaurus' default
badge--primary
- Renaming any existing
:::info Pro Feature admonitions to use the badge instead — those stay as page-level callouts
- Adding the badge to v0.4.x docs (legacy, frozen)
Reference example
Used in PR #188 (now removed during page restructure): the heading ## Coupon Codes <span class="badge badge--primary">Pro</span> rendered nicely as a visual cue. Bring it back, but everywhere it makes sense.
Summary
Add a consistent inline
<span class="badge badge--primary">Pro</span>marker after section headings that describe Pro-only functionality, so readers get a fast visual cue without having to scan for an admonition block.The pattern was used briefly in the v1.9 docs refresh and we liked it as a visual cue. Time to roll it out everywhere.
Why
We already mark Pro features two ways today:
:::info Pro Feature…) — full callout, used at the top of Pro-only pages likecustomers/index.mdx,orders/index.mdx,coupons/index.mdx. Good for context, but a bit heavy for a sub-section on a mostly-free page.The inline badge fills the gap between the two: tight enough to sit at the end of an
## Heading, loud enough to be unmissable. No custom CSS needed —badge badge--primaryis a built-in Infima class shipped with Docusaurus.Visual
```mdx
Coupon Codes Pro
```
Renders as: a small blue pill saying "Pro" at the end of the heading.
Scope — pages to apply the badge
Anywhere a sub-section on a page documents Pro-only behaviour. Suggested first pass (not exhaustive — anything new follows the same rule):
Pages that mix free and Pro content
These have free sections plus Pro sections — the inline badge belongs on the Pro headings:
Whole-page Pro features
Pages that are entirely Pro (already carry a `:::info Pro Feature` admonition near the top) — adding the badge to the page `# Title` would be redundant and ugly. Leave the title alone, keep the admonition, but use inline badges if any sub-section on that page documents a Pro-only sub-capability that goes beyond the page's headline scope.
Pages in this bucket:
When to use the badge vs the admonition
:::info Pro Featurenear the top, no inline badge on the title:::noteor:::infoblock with the detailAcceptance criteria
versioned_docs/version-1.x/**/*.mdxfor headings that describe Pro-only functionality on otherwise-free or mixed pages<span class="badge badge--primary">Pro</span>after each such heading# Titleheadings on pages that already carry a:::info Pro Featureadmonitionpnpm start) — the badge should appear as a small blue pill at the end of the heading text, not on a new linei18n/translated copies (the badge syntax is HTML so it survives translation, but verify a few)Out of scope
badge--primary:::info Pro Featureadmonitions to use the badge instead — those stay as page-level calloutsReference example
Used in PR #188 (now removed during page restructure): the heading
## Coupon Codes <span class="badge badge--primary">Pro</span>rendered nicely as a visual cue. Bring it back, but everywhere it makes sense.