CTA

The CTA (call-to-action) feature renders a card in the right-hand sidebar of a page, with a button and a short list of benefits. By default, every page shows the built-in trial card. Docsets can define their own named CTA templates and have individual pages opt into them.

Add a cta map to your docset.yml file. Each key is a template name; the value defines the button and benefits.

cta:
  beta:
    button:
      label: Join the private beta
      url: https://example.com/beta-signup
    benefits:
      - "Early access to new features"
      - "Direct line to the team"
      - "Free for beta participants"
  • button.label and button.url are required.
  • benefits is optional and limited to 3 entries.

You can also override the built-in default by defining your own trial entry — it replaces the default card sitewide for this docset.

Select a CTA on a page

Use the cta frontmatter field to select a template by id:

---
cta:
  id: beta
---

If a page omits cta, the template registered as the default for its navigation file (if any) applies; otherwise it falls back to the built-in trial CTA. An unknown id emits a build warning and is ignored.

To apply a template to every page listed in a docset.yml or nested toc.yml without editing each file, set default_cta to a template name declared in docset.yml:

# solutions/observability/toc.yml
default_cta: observability
toc:
  - file: index.md
  - file: apps/apm.md
		
# docset.yml
cta:
  observability:
    button:
      label: Get started free
      url: https://cloud.elastic.co/serverless-registration?onboarding_token=observability
    benefits:
      - "14-day free trial"
  • default_cta is available on both docset.yml and nested toc.yml files.
  • Pages inherit the nearest default_cta from their navigation file. A nested toc.yml can override the value from a parent navigation file.
  • A page's cta frontmatter always takes precedence over a navigation default.
  • Each page can only be registered with one default CTA; listing the same page twice with different defaults is a build error.

CTA buttons are tracked via OpenTelemetry: a cta_viewed event fires the first time a card becomes visible, and a cta_clicked event fires on click. Both events carry the CTA's name, URL, label, and placement, so click-through rate can be compared across templates.