Skip to content

Adopt inline 'Pro' badge on Pro-only section headings across the docs #189

Description

@kilbot

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

  • Audit versioned_docs/version-1.x/**/*.mdx for headings that describe Pro-only functionality on otherwise-free or mixed pages
  • Add <span class="badge badge--primary">Pro</span> after each such heading
  • Do not add the badge to page-level # Title headings on pages that already carry a :::info Pro Feature admonition
  • Verify rendering in dev (pnpm start) — the badge should appear as a small blue pill at the end of the heading text, not on a new line
  • Spot-check on mobile width — the heading should still wrap cleanly
  • Update i18n/ translated copies (the badge syntax is HTML so it survives translation, but verify a few)

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions