influxdata / influxdata/docs-v2

Generated .md frontmatter: clarify edition slug vs. release version

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

## Summary

The generated LLM-facing `.md` twins emit a `version` frontmatter field whose
value is the docs **edition/variant slug** (`core`, `enterprise`, `v2`, `v1`,
`cloud`, `cloud-dedicated`, ...), not a software release version. Combined with
`product` (the full product name), this is redundant and mis-suggestive:

```yaml
product: InfluxDB 3 Core
version: core # edition slug, not a release
```

The actual release version lives in `data/products.yml` as `latest_patch`
(e.g. `3.9.3`) and is never surfaced in the twins.

## Where it comes from

`scripts/rust-markdown-converter/build.rs` reads only `name` and
`versions[]`/`latest` from `data/products.yml` and bakes a
`URL pattern -> (name, version-slug)` map. `latest_patch` is not read.

## Proposed improvement

1. Stop overloading `version`. Emit the edition slug under a clearer key such as
`edition`.
2. Optionally add a real release field (e.g. `product_patch: 3.9.3`) sourced
from `latest_patch` — **only where it exists**. Continuously deployed cloud
products (Cloud Serverless, Cloud Dedicated, Clustered) have no patch, so this
field must be omitted there rather than left blank.

## Consumer impact (why this is its own change)

Renaming/adding frontmatter changes the contract for ~4,684 published twins and
everything that parses them: `llms-full.txt` builders, the Cypress markdown
validator, and external LLM consumers. It is a content-schema decision, separate
from the Rust-converter migration.

## Scope notes

- Pairs naturally with the existing follow-up to unify the URL->product map onto
`data/products.yml` across the CLI (`scripts/docs-cli/lib/product-resolver.js`)
and TypeScript (`assets/js/utils/product-mappings.ts`).
- Discovered during the Rust markdown converter migration
(branch `fix-rust-markdown-conversion`), which deliberately keeps `version:
` for drop-in parity.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with scripts/rust-markdown-converter/build.rs and data/products.yml to trace the generated frontmatter values. Then inspect the named llms-full.txt builders, Cypress markdown validator, scripts/docs-cli/lib/product-resolver.js, and assets/js/utils/product-mappings.ts. Done means the agreed frontmatter contract is applied consistently, optional latest_patch values are handled correctly, and affected validation/build steps pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
cypress, javascript, rust, typescript
Domain
build-system, documentation, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.