CTA: allow scoping templates to path subtrees via paths

[bmorelli25]

Why

The right-gutter CTA card can now be customized per page via cta frontmatter (#3602) 🎉 . This PR propsoes a new way customize the CTA card. elastic/docs-content-internal#1475 requests adding a custom "Get started free" CTA and onboarding_token to all solution-specific pages under solutions/observability/, solutions/security/, and the solutions/searc. Doing this in frontmatter alone means editing ~600 files. Over time as new pages are added, it is innevitable that some or all will forget to add this frontmatter and we'll get to a place where a random selection of pages uses the custom CTA.

The proposed solution

A CTA template in docset.yml can now declare paths: docset-relative path prefixes it applies to. Every page under a listed prefix gets that template, no frontmatter needed.

cta:
  observability:
    button:
      label: Get started free
      url: https://cloud.elastic.co/serverless-registration?onboarding_token=observability
    paths:
      - solutions/observability

Resolution order for a page:

1. An explicit, known cta frontmatter id (unchanged, always wins)
2. The most specific paths scope covering the page
3. The built-in trial default

This makes the docs-content side of #1475 a small docset.yml-only PR, and the pages that already carry cta frontmatter (e.g. the monitor-kubernetes / monitor-aws pages from elastic/docs-content#7135) keep their more specific CTA automatically.

Details: matching rules, edge cases, and one behavior change

• Whole-segment matching. solutions/observability covers solutions/observability/apps/apm.md but not solutions/observability-labs/index.md. Prefixes are normalized (slashes and separators), matched case-insensitively.
• Overlapping scopes. The longest matching prefix wins, so a docset can scope observability to solutions/observability and a more specific template to solutions/observability/get-started.
• Conflicts are build errors. The same path claimed by two templates, or an empty path, fails the build rather than resolving silently.
• Behavior change for unknown frontmatter ids. Previously an unknown cta id warned and fell back straight to the default trial card. It still warns, but is now ignored, so a path scope covering the page applies instead. The section CTA is more relevant than the generic card, and the warning still points at the typo.
• Isolated builds. A path-scoped CTA resolves to a named, non-default template, so it renders in isolated builds too (same as explicit frontmatter) — contributors can preview it. The built-in default remains assembler-only.

Docs for the new key are added to docs/configure/content-set/cta.md.

Test plan

• 9 new unit tests in ConfigurationFileCtaTests covering precedence, whole-segment matching, longest-prefix-wins, normalization, and the two error cases (594/594 pass)
• Full solution builds with 0 errors
• Manually verify a docset with a paths scope renders the scoped CTA on pages under the prefix and the default elsewhere

Made with Cursor

[bmorelli25]

@elastic/docs-engineering I have this proposal for you. If it's too far from your vision LMK and we can close this.