influxdata / influxdata/docs-v2

Add automated checks for shared content quality

Open
#6,853 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Context

These TODOs were identified during a review of the `content-editing` skill and represent automation opportunities to improve shared content quality and consistency.

## Tasks

### 1. Validate `alt_links` for shared content with differing paths

Add an automated check to validate that `alt_links` frontmatter is present when shared content paths differ across products.

**Example:** If a page exists at `/influxdb3/core/admin/tokens/` but `/influxdb3/cloud-serverless/reference/tokens/`, the frontmatter files should include `alt_links` to cross-reference them.

### 2. Check for product-specific URL patterns in shared content

Add a check for product-specific URL patterns that shouldn't appear in shared content.

**Example:** Cloud Serverless uses `/reference/regions` for region URLs, but Cloud Dedicated/Clustered don't have this page (cluster URLs come from account setup). Shared content shouldn't hardcode these product-specific paths.

### 3. Validate resource term links

Add a check/helper to ensure product resource terms (tokens, databases, buckets) link to proper admin pages using the `/influxdb3/version/admin/` pattern.

**Example:** When documentation mentions "database token", it should link to the appropriate `/influxdb3/version/admin/tokens/` page.

### 4. Improve `code-placeholder-key` workflow

The current `docs placeholders` command adds `placeholders` attributes to code blocks but doesn't generate the "Replace the following:" lists with `{{% code-placeholder-key %}}` shortcodes.

**Options:**
- Improve automation to generate these replacement lists automatically
- Simplify by removing `code-placeholder-key` shortcode if the `placeholders` attribute alone is sufficient

## Related

- `.claude/skills/content-editing/SKILL.md` - Content editing workflow skill
- `scripts/docs-cli/docs-cli.js` - docs CLI implementation

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading .claude/skills/content-editing/SKILL.md and scripts/docs-cli/docs-cli.js, then inspect the current docs placeholders command. Map how shared-content frontmatter, product-specific URLs, resource-term links, and code-placeholder-key are handled. Done means the agreed checks or workflow improvements are automated and verified against representative documentation cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.