influxdata · jstirnaman · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
@@ -0,0 +1,107 @@
+# Documenting version availability
+
+How to state which product versions and editions a page or feature applies to.
+
+This page covers the decisions: which marker to use, which surface carries
+which fact, where a page lives, and when a notice is removed.
+For field syntax, see [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md).
+For how Markdown twins and corpora are published, see
+[DOCS-AI-VISIBILITY.md](DOCS-AI-VISIBILITY.md).
+
+## Choose a marker
+
+Match the marker to the scope of the version constraint.
+
+| Scope                                                      | Use                                               | Example                                      |
+| ---------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------- |
+| The whole page applies to a version range                  | `metadata:` frontmatter                           | `metadata: [Explorer v1.9 and earlier]`      |
+| The whole page is one of a generated set with a real range | `introduced`, `deprecated`, `removed` frontmatter | `introduced: "v1.9.0"`                       |
+| One section applies to a version range                     | Heading attribute                                 | `## Configure user auth {metadata="v1.10+"}` |
+
+Use `metadata:` when you need to state a ceiling or an exact phrase.
+The `introduced`/`deprecated`/`removed` fields render as a range, such as
+"InfluxDB 3 Explorer v1.0.0 – v1.10.0", which doesn't say which release is the
+last working one.
+Telegraf plugin pages use the range fields because the values are generated
+from plugin metadata.
+
+Don't state a version constraint only in body text.
+Frontmatter markers render in a list under the page h1 and appear above the
+lede in the page's Markdown twin, which is the text a retrieval system reads
+first.
+
+## Choose a surface
+
+Each surface reaches a different audience.
+Decide which one carries the fact before you write it.
+
+| Surface                                           | Reaches                                                  | Use for                                                                 |
+| ------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Frontmatter markers and the lede                  | Readers, search engines, Markdown twins, `llms-full.txt` | Any version or edition fact a reader or an agent needs to act correctly |
+| `prepend` / `append` frontmatter (with `cascade`) | Same as above, on every page it cascades to              | A transition notice that must appear in the twin                        |
+| `data/notifications.yaml`                         | Readers only                                             | A dated announcement, such as a release or a scheduled change           |
+
+Notifications render in the site footer through
+`layouts/partials/footer/notifications.html`, outside the article element.
+They don't appear in Markdown twins or in `llms-full.txt`.
+A fact that exists only in a notification is invisible to every AI consumer of
+the docs, so don't use a notification as the only statement of a version
+requirement.
+
+Cascaded `prepend` content appears in the twin of every page it reaches, which
+makes the first chunk of those pages similar to each other.
+Keep cascaded notices to a few lines, and remove them when the transition ends.
+
+## Place a feature page
+
+When a feature spans two products, such as a UI feature that depends on a
+server capability:
+
+1. Put the canonical page in the product that owns the behavior.
+2. Add `alt_links` so the product switcher moves readers to the equivalent page
+   in the other product.
+3. Add `related` entries from the other product's page.
+
+Don't duplicate the instructions in both products.
+If both products need the same body, use `source:` to share the content and set
+`canonical: self` on the page whose URL marks the product identity.
+
+## Include a version check
+
+A page that documents a version-gated feature states how to verify the version,
+or links to a page that does.
+Give both a local check and a check that works against a running instance, so
+that a reader without shell access to the server can still confirm the version.
+
+Local:
+
+```bash
+influxdb3 --version
+```
+
+Running instance:
+
+```sh
+curl --get "http://localhost:8181/ping" \
+  --header "Authorization: Bearer AUTH_TOKEN"
+```
+
+The `/ping` response includes the `x-influxdb-version` and `x-influxdb-build`
+headers, and `version` and `revision` in the body.
+Because `x-influxdb-build` reports `Core` or `Enterprise`, `/ping` is the only
+check that answers both the version question and the edition question.
+Use `GET`; a `HEAD` request returns `404`.
+
+## Retire a notice
+
+Every temporary notice names the release that removes it.
+
+- For a `cascade.prepend` notice, record the removal release in the exec-plan
+  for the change that added it.
+- For a `data/notifications.yaml` entry, record the removal release with the
+  entry `id`, so the entry can be found and deleted without reading the message
+  text.
+
+Version markers in frontmatter are permanent.
+They describe a fact about the release, not a temporary state, so leave them in
+place after the transition ends.
@@ -0,0 +1,128 @@
+# Explorer install docs: route by version and edition
+
+**Status:** In review — PR [#7734](https://github.com/influxdata/docs-v2/pull/7734)
+**Closes:** [#6702](https://github.com/influxdata/docs-v2/issues/6702)
+
+## Goal
+
+Restructure the InfluxDB 3 Explorer install documentation so that each page
+states which Explorer versions and which InfluxDB 3 editions it applies to.
+After this change, `/influxdb3/explorer/install/` routes readers by version
+instead of presenting Docker as the only deployment method, and the Docker
+instructions live on a child page that declares its version ceiling in
+frontmatter, in the lede, and in the Markdown twin.
+
+## Why now
+
+Explorer v1.9 is the last release distributed as a standalone Docker container.
+Starting with v1.10, Explorer is included with InfluxDB 3 Enterprise and is
+deployed as WebAssembly (WASM). The current pages have no version or edition
+scoping:
+
+- `content/influxdb3/explorer/install.md` documents only Docker.
+- `content/influxdb3/explorer/_index.md` repeats a `docker pull` quick start.
+- `content/influxdb3/explorer/about/_index.md` states full Core and Enterprise
+  support with no end version.
+- `data/products.yml` lists `Docker` in `schema.operating_system`, which feeds
+  the JSON-LD `SoftwareApplication` node.
+
+Each of these tells readers, search engines, retrieval systems, and coding
+agents that Explorer is a Docker container that works with Core. Doing the
+restructure before v1.10 ships means the corpus and search index carry the
+version scoping before the release changes the answer.
+
+Issue #6702 reports the related gap: the docs never state outright which
+distributions exist, so a docs-grounded assistant can only infer the
+limitation.
+
+## Decisions
+
+- **Keep `/influxdb3/explorer/install/` as the URL and convert it to a
+  version-routing hub.** The URL holds the search ranking, seven inbound
+  in-repo links (three of them deep anchors), the `llms.txt` corpus entry, and
+  any existing model memory. Moving the page under `/get-started/` or demoting
+  it in the navigation would break those without addressing the actual problem,
+  which is the page content, not its address.
+- **Move the Docker body to `install/docker.md` unchanged.** Keeping the body
+  intact preserves the three anchors that other pages link to:
+  `#choose-operational-mode`, `#network-exposure-and-access-control`, and
+  `#set-file-permissions-for-upgrades`.
+- **Do not redirect `/install/` to `/install/docker/`.** A redirect would send
+  every "install Explorer" search result and every agent's first URL guess to
+  the deprecated path.
+- **Use `metadata: [Explorer v1.9 and earlier]` rather than
+  `introduced`/`deprecated`.** Both render into the `ul.metadata` list under the
+  h1 and into the first line of the Markdown twin, verified against
+  `/influxdb3/clustered/reference/cli/influxctl/query/index.md` (`* influxctl
+  2.4.0+`) and `/telegraf/v1/input-plugins/jenkins/index.md` (`* Telegraf
+  v1.9.0+`). The `introduced`/`deprecated` pair renders as a range
+  ("v1.0.0 – v1.10.0"), which is ambiguous about the last working release.
+  `metadata` states the ceiling exactly.
+- **Keep the Docker page published and indexed.** Explorer v1.9 remains
+  supported, and removing or hiding the instructions creates a retrieval dead
+  end. A page that states its own version ceiling is not misleading.
+- **Use `cascade.prepend` on `explorer/_index.md` for the transition notice,
+  not a template banner.** `article/stable-version.html` is gated on a
+  hardcoded product whitelist and a `/vN/` URL segment, neither of which
+  applies to Explorer, and extending it would add magic values to a template
+  (see `.claude/rules/layouts.md`). `article/special-state.html` has the same
+  problem. `cascade.prepend` is documented in `DOCS-FRONTMATTER.md` and needs no
+  template change.
+- **Accept the twin cost of the cascaded notice, and remove it after v1.11.**
+  Prepended content appears in every Explorer Markdown twin and in
+  `llms-full.txt`, which makes the first chunk of all 12 Explorer pages more
+  alike (the twin-hygiene problem tracked in
+  [#7323](https://github.com/influxdata/docs-v2/issues/7323)). The notice is
+  three lines and is worth that cost while the transition is live.
+- **Document version verification with `GET /ping`, not only
+  `influxdb3 --version`.** WASM availability depends on the InfluxDB 3 server
+  version and build, not on Explorer alone. `GET /ping` returns
+  `x-influxdb-version` and `x-influxdb-build` (`Core` or `Enterprise`) in
+  headers and `version` in the body
+  (`api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml`), so one
+  command answers both questions and works headlessly against a remote
+  instance. A `HEAD` request returns 404, so the docs specify `GET`.
+
+## Explicitly out of scope
+
+- WASM deployment instructions under `/influxdb3/enterprise/`. Those wait until
+  v1.10 ships; this change only prepares the routing and cross-links.
+- `data/products.yml` updates to `latest_patch` and `schema.operating_system`.
+  Both change on release day, not before.
+- The `localhost` connection failure reported in
+  [#7333](https://github.com/influxdata/docs-v2/issues/7333). It affects the
+  Docker instructions but is a separate content fix.
+- Extending `article/stable-version.html` to support products without a `/vN/`
+  URL segment.
+
+## How to update
+
+The Explorer version ceiling appears in four places on
+`content/influxdb3/explorer/install/docker.md`: the `metadata` frontmatter, the
+`description` frontmatter, the lede, and the transition notice cascaded from
+`content/influxdb3/explorer/_index.md`. Update the notice in `_index.md` once
+and it changes on every Explorer page. Remove the `cascade.prepend` block when
+v1.11 ships.
+
+## Verification
+
+1. `npx hugo --quiet` builds without errors.
+2. Confirm the three anchors still resolve within `install/docker/`, and that no
+   in-repo link points at `/influxdb3/explorer/install/#` for a Docker-only
+   section.
+3. `yarn check:md-coherence` confirms the head link, `sitemap-md.xml`, and
+   corpus surfaces agree after the URL structure changes.
+4. Run the Cypress navigation tests. Converting a single page to a section
+   changes the menu tree.
+5. After deploy, check the published Markdown twins. PR previews return 404 for
+   twins, so use production or staging:
+
+   ```sh
+   curl -s --compressed https://docs.influxdata.com/influxdb3/explorer/install/index.md | head -20
+   curl -s --compressed https://docs.influxdata.com/influxdb3/explorer/install/docker/index.md | head -20
+   ```
+
+   The Docker twin starts with `* Explorer v1.9 and earlier` above the lede.
+6. Ask the documentation MCP server "How do I install InfluxDB 3 Explorer?"
+   after the corpus rebuilds. The answer routes by version instead of returning
+   `docker run`.
@@ -0,0 +1,99 @@
+# Explorer v1.10 release readiness
+
+**Status:** In progress — PR [#7734](https://github.com/influxdata/docs-v2/pull/7734)
+**Refs:** [2026-09-02-explorer-install-version-routing.md](2026-09-02-explorer-install-version-routing.md)
+
+## Goal
+
+Define the documentation work for the InfluxDB 3 Explorer v1.10 release and the
+InfluxDB 3 Enterprise release that carries it. The install restructure prepares
+the version routing; this plan covers what changes when v1.10 ships.
+
+## Decisions
+
+- **Every new feature page tells the reader how to check whether their version
+  has the feature.** A version marker states the requirement, but a reader
+  arriving from search doesn't know which version they're running. Each feature
+  page states the requirement and shows the check, or links to the check in the
+  install hub. See
+  [DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md).
+- **The check covers both the Explorer version and the InfluxDB 3 server
+  version and edition.** A v1.10 feature can require both. `GET /ping` returns
+  `x-influxdb-version` and `x-influxdb-build` (`Core` or `Enterprise`), so it
+  answers the server half in one request, including against a remote instance.
+- **Merge at release rather than publishing with `draft: true`.** Content pages
+  merge on release day. Use `draft: true` only when a page must exist in the
+  branch before the release for a specific reason, such as a link target that
+  other merged content depends on.
+- **Use `data/notifications.yaml` for the release announcement, and keep the
+  version facts in the pages.** Notifications render in the footer, outside the
+  article, so they don't appear in Markdown twins or `llms-full.txt`. The
+  announcement is for readers; the version scope that agents and retrieval
+  systems need stays in frontmatter and the lede.
+- **Order the release-day merge so no published page points at an unpublished
+  one.** Feature pages first, then the install hub lede, then
+  `data/products.yml`.
+
+## Before the release
+
+1. Write each new feature page with its version marker: page-level `metadata:`
+   when the whole page is new in v1.10, a `{metadata="v1.10+"}` heading
+   attribute when only a section is.
+2. Add the version check to each feature page. State the Explorer version the
+   feature requires and, when the feature depends on the server, the InfluxDB 3
+   version and edition. Show the `/ping` request or link to the check in the
+   install hub.
+3. Add the WASM deployment instructions to the InfluxDB 3 Enterprise section,
+   including the server version that introduced them.
+4. Add `alt_links` in both directions between each Explorer feature page and
+   the Enterprise page that documents the server side.
+5. Write the release notes entry in
+   `content/influxdb3/explorer/release-notes/_index.md`.
+6. Add a commented-out `data/notifications.yaml` entry with the final `id`,
+   `scope`, `title`, and `slug`, following the `influxdb3-cloud-ga` stub
+   already in that file.
+
+## On release day
+
+Merge in this order.
+
+1. Feature pages and the Enterprise WASM deployment page.
+2. The install hub lede at `content/influxdb3/explorer/install/_index.md`, so
+   the WASM path is described first and Docker reads as the path for v1.9 and
+   earlier.
+3. `data/products.yml`: set `latest_patch` to the new Explorer version and
+   update `schema.operating_system`, which lists `Docker` and feeds the JSON-LD
+   `SoftwareApplication` node.
+4. The release notes entry.
+5. The `data/notifications.yaml` entry, uncommented.
+
+## At v1.11
+
+1. Delete the `data/notifications.yaml` entry by `id`.
+2. Remove the `cascade.prepend` transition notice from
+   `content/influxdb3/explorer/_index.md`.
+3. Leave the frontmatter version markers. They state a fact about the release,
+   not a temporary condition.
+
+## Verification
+
+1. `npx hugo --quiet` builds without errors.
+
+2. `yarn check:md-coherence` confirms the head links, `sitemap-md.xml`, and
+   corpus surfaces agree after the new pages publish.
+
+3. The notification renders on its scoped paths and not on the excluded ones.
+
+4. After deploy, the version marker leads each new page's Markdown twin. PR
+   previews return 404 for twins, so use production or staging:
+
+   ```sh
+   curl -s --compressed https://docs.influxdata.com/influxdb3/explorer/<page>/index.md | head -20
+   ```
+
+5. The notification text appears in neither the twins nor
+   `https://docs.influxdata.com/influxdb3/explorer/llms-full.txt`. If it does,
+   it was added to the wrong surface.
+
+6. Ask the documentation MCP server how to use a new v1.10 feature. The answer
+   states the version requirement and how to check it.