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:
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
- Stop overloading
version. Emit the edition slug under a clearer key such as
edition.
- 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: <slug> for drop-in parity.
Summary
The generated LLM-facing
.mdtwins emit aversionfrontmatter field whosevalue is the docs edition/variant slug (
core,enterprise,v2,v1,cloud,cloud-dedicated, ...), not a software release version. Combined withproduct(the full product name), this is redundant and mis-suggestive:The actual release version lives in
data/products.ymlaslatest_patch(e.g.
3.9.3) and is never surfaced in the twins.Where it comes from
scripts/rust-markdown-converter/build.rsreads onlynameandversions[]/latestfromdata/products.ymland bakes aURL pattern -> (name, version-slug)map.latest_patchis not read.Proposed improvement
version. Emit the edition slug under a clearer key such asedition.product_patch: 3.9.3) sourcedfrom
latest_patch— only where it exists. Continuously deployed cloudproducts (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.txtbuilders, the Cypress markdownvalidator, and external LLM consumers. It is a content-schema decision, separate
from the Rust-converter migration.
Scope notes
data/products.ymlacross the CLI (scripts/docs-cli/lib/product-resolver.js)and TypeScript (
assets/js/utils/product-mappings.ts).(branch
fix-rust-markdown-conversion), which deliberately keepsversion: <slug>for drop-in parity.