influxdata / influxdata/docs-v2

AI visibility: add ref-card shortcode for inline section-level reference callouts

Open
#7,244 0 comments 0 reactions 0 assignees View on GitHub
enhancement InfluxDB v3 platform
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.