influxdata / influxdata/docs-v2

Rationalize content_path in data/products.yml to always include version

Open
#7,212 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

Follow-up to PR #7211 (Markdown autodiscovery). The autodiscovery work surfaced an inconsistency in \`data/products.yml\`:

- For some products, \`content_path\` is the versioned path (e.g., \`influxdb3/core\`, \`influxdb/v2\`).
- For others, \`content_path\` is the **parent** product directory and the version segment is implicit (e.g., \`telegraf\` but content lives at \`content/telegraf/v1/\`).

This inconsistency forces every downstream consumer to derive the versioned path with combine-content_path-plus-versions logic. PR #7211 added one such derivation utility at \`scripts/lib/corpus-paths.js\` and mirrored the same logic in Hugo templates. Other consumers (\`.github/scripts/workflow-utils.js\`, \`assets/js/utils/product-mappings.ts\`, sidebar/topnav layouts) handle the inconsistency in their own ways.

## Proposed fix

Rationalize \`content_path\` so it **always** points to the versioned content path:

| Product | Current \`content_path\` | Proposed |
|---|---|---|
| telegraf | \`telegraf\` | \`telegraf/v1\` |
| chronograf | \`chronograf\` | \`chronograf/v1\` |
| kapacitor | \`kapacitor\` | \`kapacitor/v1\` |
| enterprise_influxdb | \`enterprise_influxdb\` | \`enterprise_influxdb/v1\` |
| flux | \`flux\` | \`flux/v0\` |

Products with versioned \`content_path\` (\`influxdb3/core\`, \`influxdb/v2\`, etc.) stay unchanged. Products with object-form \`content_path\` (e.g., \`influxdb\` with \`{v2, v1}\`) stay unchanged.

## Audit checklist before changing

Each \`content_path\` consumer needs to be verified:

- [ ] \`.github/scripts/workflow-utils.js\` (label mapping)
- [ ] \`scripts/lib/corpus-paths.js\` (created in #7211)
- [ ] \`assets/js/utils/product-mappings.ts\` (URL → product matching)
- [ ] \`helper-scripts/build-agent-instructions.js\`
- [ ] All Hugo layouts iterating \`.Site.Data.products\` (sidebar, topnav, footer, etc.)
- [ ] \`api-docs/scripts/generate-openapi-articles.ts\`
- [ ] PR auto-labeler workflows

For each, ask: does the consumer expect \`content_path\` to be the parent or the versioned path? Update consumers that expect parent-form (or that strip a trailing version, etc.).

## Why this is a follow-up rather than part of #7211

PR #7211 introduces a derivation utility (\`scripts/lib/corpus-paths.js\`) that handles both conventions. The autodiscovery feature works correctly either way. Rationalizing \`content_path\` is a cross-cutting refactor that benefits more than just autodiscovery, but it's not required for autodiscovery to ship.

Once \`content_path\` is rationalized, \`scripts/lib/corpus-paths.js\` simplifies dramatically (just iterate, no version-appending heuristic) and \`workflow-utils.js\` becomes simpler too.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with data/products.yml and compare the listed content_path values against consumers in .github/scripts/workflow-utils.js, scripts/lib/corpus-paths.js, assets/js/utils/product-mappings.ts, helper-scripts/build-agent-instructions.js, Hugo layouts, api-docs/scripts/generate-openapi-articles.ts, and auto-labeler workflows. Verify whether each consumer expects parent or versioned paths, then update affected consumers and confirm every product resolves to the intended content path without breaking existing versioned or object-form entries.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
documentation, tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.