diff --git a/.agents/skills/ai-visibility/SKILL.md b/.agents/skills/ai-visibility/SKILL.md index fced33121a..d40c045121 100644 --- a/.agents/skills/ai-visibility/SKILL.md +++ b/.agents/skills/ai-visibility/SKILL.md @@ -20,6 +20,13 @@ from recommendations. yarn build:md yarn check:md-coherence yarn check:jsonld-links +node scripts/check-jsonld-links.js --public-dir +node scripts/check-md-alternate-coherence.js --public-dir ``` +Both check scripts accept `--public-dir`, so they run against a +`hugo --destination ` build without `build:md`. Without the twins, +`check:md-coherence` fails for every page in the site; that is an environment +gap, not a regression. + Load the applicable reference only for its artifact class. diff --git a/.agents/skills/content-editing/references/fact-checking.md b/.agents/skills/content-editing/references/fact-checking.md index 518b4c9c51..3314222c16 100644 --- a/.agents/skills/content-editing/references/fact-checking.md +++ b/.agents/skills/content-editing/references/fact-checking.md @@ -3,3 +3,13 @@ Use the hosted documentation search MCP for API syntax and product behavior. Read the primary product documentation, record uncertainty, and do not turn a search snippet into an unsupported technical claim. + +Verify a version requirement against the feature's own page in `content/`. An +execution plan records the requirement as of its write date, so treat it as a +lead that signals previous state or future intent. + +When a feature ships in more than one deployment mode, check which mode a +prerequisite applies to before you link it. Condition the guidance on the mode +and leave the undocumented mode unstated. + +Link to the page that holds the procedure, not to the product landing page. diff --git a/.agents/skills/docs-testing/references/specialized-checks.md b/.agents/skills/docs-testing/references/specialized-checks.md index c8b3bb8275..25742f8f47 100644 --- a/.agents/skills/docs-testing/references/specialized-checks.md +++ b/.agents/skills/docs-testing/references/specialized-checks.md @@ -3,3 +3,8 @@ Layouts require Hugo and Cypress runtime coverage. Assets require their scoped build or lint. API specs require `yarn build:api-docs`. Shell, workflows, and other deferred paths need a deliberate review until verifier support expands. + +A Hugo build that exits 0 but renders only a few pages is a build artifact, not +a template bug. Rebuild into a fresh `--destination` with no other Hugo process +running, then investigate. A check that fails for every page in the site points +at a missing build step or a missing dependency, not at your change. diff --git a/AGENTS.md b/AGENTS.md index e2dde9d2c0..ae4810a7ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,10 @@ yarn validate:agent-instructions - Preserve unrelated working-tree changes. +- Check `git log` before you treat the staged diff as the whole change. If the + branch carries a commit you didn't make, tell the user instead of squashing + or amending it. + - Never cancel Hugo builds or code-block tests. Give Hugo at least 180 seconds and long code-block suites 30 minutes. @@ -35,6 +39,10 @@ yarn validate:agent-instructions - Use `python`, not `py`, for code block language identifiers. +- Some sandboxes block writes to `api.github.com` while GET requests succeed. + If a `gh` write fails that way, give the user the exact command to run + instead of retrying. + ## Choose checks `git commit` runs staged-file hooks. Do not manually run `yarn lint` before a diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md index bc50ffa40b..2e34977641 100644 --- a/DOCS-CONTRIBUTING.md +++ b/DOCS-CONTRIBUTING.md @@ -168,6 +168,23 @@ Save images using the following naming format: `project/version-context-descript For example, `influxdb/2-0-visualizations-line-graph.png` or `influxdb/2-0-tasks-add-new.png`. Specify a version other than 2.0 only if the image is specific to that version. +#### Links to procedures and prerequisites + +Link to the page that contains the steps, not to the parent landing page. +"See the Enterprise documentation" makes the reader hunt for the procedure. +Name the procedure and link to it directly. + +Prerequisites often differ by deployment mode. +When a product ships in more than one mode, for example a Docker container and an +integrated build, don't send every reader to mode-specific instructions. +Condition the guidance on the mode: "If you run the Docker container, ...". +If the other mode has no documented equivalent, say nothing about it rather than +inventing a parallel claim. + +Verify a version requirement against the shipped documentation for that feature. +An execution plan states the requirement as of the day someone wrote it. +Search for the feature's own page and restate what it says. + #### InfluxData Support links When linking to InfluxData Support, use one of these URLs: diff --git a/DOCS-FRONTMATTER.md b/DOCS-FRONTMATTER.md index de6bdd37c6..845310c431 100644 --- a/DOCS-FRONTMATTER.md +++ b/DOCS-FRONTMATTER.md @@ -206,13 +206,33 @@ alt_links: core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist ``` -Supported product keys for InfluxDB 3: - -- `core` -- `enterprise` -- `cloud-serverless` -- `cloud-dedicated` -- `clustered` +`layouts/partials/topnav/product-selector.html` defines the supported keys in the +`$productInfo` merge. +That template is the authoritative list. +Check it before you assume a product can't carry a cross-link. + +| Product path | `alt_links` key | +| ---------------------------- | --------------------- | +| `influxdb3/core` | `core` | +| `influxdb3/enterprise` | `enterprise` | +| `influxdb3/cloud` | `cloud3` | +| `influxdb3/cloud-serverless` | `cloud-serverless` | +| `influxdb3/cloud-dedicated` | `cloud-dedicated` | +| `influxdb3/clustered` | `clustered` | +| `influxdb3/explorer` | `explorer` | +| `influxdb/v1` | `v1` | +| `influxdb/v2` | `v2` | +| `influxdb/cloud` | `cloud` | +| `enterprise_influxdb/v1` | `enterprise_v1` | +| `telegraf/v1` | `telegraf` | +| `telegraf/controller` | `telegraf_controller` | +| `telegraf/enterprise` | `telegraf_enterprise` | +| `chronograf/v1` | `chronograf` | +| `kapacitor/v1` | `kapacitor` | +| `flux/v0` | `flux` | + +The key doesn't always match the last path segment. +InfluxDB 3 Cloud uses `cloud3` because `influxdb/cloud` already owns `cloud`. ### Prepend and Append @@ -262,6 +282,23 @@ cascade: > `llms-full.txt` corpora. > See [LLM Markdown generation](DOCS-DEPLOYING.md#llm-markdown-generation). +### Metadata messages + +Use the `metadata` frontmatter to render short tag strings under the page h1. +`layouts/partials/article/page-meta.html` renders each list item as an `
  • ` in +the page metadata list and runs it through `markdownify`. + +Keep each string short. +Use one list item per constraint instead of one long string. + +```yaml +metadata: [InfluxDB 3 Core, InfluxDB 3 Enterprise earlier than v3.11] +``` + +`metadata` isn't limited to version ceilings. +Product, edition, and version constraints all work as separate items. +The `updated_in` and `date` fields render in the same list. + ### Cascade To automatically apply frontmatter to a page and all of its children, use the