influxdata / influxdata/docs-v2
AI visibility: add ref-card shortcode for inline section-level reference callouts
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Goal
Add a `ref-card` shortcode for inline section-level reference callouts so writers can surface "look up while reading" links without redirecting to a `related:` block (which is page-level "browse after reading").
Parent: #7230 (Phase 0)
## Context
Today's options for inserting a cross-link inside a section:
- `related:` frontmatter — renders as a page-level block, wrong place for mid-section reference
- Inline markdown link — no visual signal that this is a definitional jump-off
- `> [!Tip]` callout — works but the tip shortcode wasn't designed for reference cards and the visual treatment doesn't communicate "reference, not advice"
A `ref-card` shortcode fills the gap with intentional styling.
## Acceptance criteria
- New shortcode \`layouts/shortcodes/ref-card.html\`
- Usage: \`{{< ref-card title="Token scopes" url="/influxdb3/core/admin/tokens/scope/" >}}\` (optional \`description\` and \`type\` parameters)
- Styled distinctly from \`> [!Tip]\` and \`{{< note >}}\` — visually communicates "reference card"
- Documented in \`DOCS-SHORTCODES.md\` with the rule: \`related:\` is page-level "browse after reading"; \`ref-card\` is section-level "look up while reading"
- Example in \`content/example.md\`
- Cypress assertion on the example page that ref-card renders and links resolve
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with layouts/shortcodes/ref-card.html, then read DOCS-SHORTCODES.md and content/example.md for the documented usage and example conventions. Add the shortcode, documentation, example, and Cypress assertion; done means the example renders a visually distinct reference card and its links resolve.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cypress, javascript
- Domain
- documentation, testing
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100