Rename the service-name placeholder from <MY_SERVICE_NAME> to
<YOUR_SERVICE_NAME> across the SDK pages and the validator allowlist, matching
the <YOUR_...> convention of the other standardized placeholders.
The HyperDX in-app onboarding mirrors the SDK guides under
docs/clickstack/ingesting-data/sdks/ from this single source of truth, so it
parses them by convention. This standardizes those conventions and adds a
scoped validator so a drifting page cannot silently break the app's parsing.
- Add a `<ClickStackIntegrates signals={[...]} />` component (new snippet at
docs/snippets/components/ClickStackIntegrates/) that renders the
"This guide integrates" indicator as ClickHouse-yellow pills for the
supported signals. The `signals` prop (logs/metrics/traces) is the single
source of truth the app parses; it replaces the drifting hand-written blocks
(HTML tables and ad-hoc bullet lists across the pages).
- Standardize replaceable env-var placeholders: `<YOUR_INGESTION_API_KEY>`
(was also bare, `***`-wrapped, and `<YOUR_INGESTION_KEY>`),
`<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>` for the OTLP endpoint (was
localhost:4318 / your-otel-collector:4318, and fixes the
`<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>` typo), and `<MY_SERVICE_NAME>` for the
service name (was `<NAME_OF_YOUR_APP_OR_SERVICE>` / `<YOUR_APP_NAME>`).
- Fix a stray newline in the index keywords.
- Add ci/jobs/scripts/docs/sdk_docs_check.py enforcing all of the above: the
ClickStackIntegrates component + valid signals, an allowlist of `<UPPER_SNAKE>`
placeholders (so a new typo/variant is caught generically), and exact
deployment tab titles (Managed ClickStack / ClickStack Open Source). It is
wired into the existing "Docs check (Mintlify)" job and gated to run only when
an SDK page, the component, or the validator changes.
Closes: https://linear.app/clickhouse/issue/HDX-5262/standardize-clickstack-sdk-docs-for-in-app-onboarding
Verify deleted landing pages against docs/_migration/slug-map.csv, restore pages with introductory content, and route every legacy landing URL directly to its canonical overview.
Verified: https://clickhouse.com/docs/cloud/manage/api/swagger
Move navigation roots into their groups as first children, remove redundant landing pages, update sidebar labels and links, and redirect every removed route to its canonical overview page.
Verified the legacy Swagger entry point:
https://clickhouse.com/docs/cloud/manage/api/swagger
Rewrites every <Step> whose first content line is a markdown heading
into <Step title="..." id="...">, so the step number no longer
renders above the title. Explicit {#anchor} slugs are carried
verbatim into id (the DOM anchor target, so existing deep links keep
resolving), anchorless headings get their previously auto-generated
slug frozen, and titles with inline markup become JSX fragment
props, e.g. title={<>Create <code>column_user</code></>}.
1207 steps in 186 files, English content and snippets only; the
generated locale trees are left untouched for the translation
pipeline to regenerate. All modified files pass an MDX parse check,
and the links, locale-links, and redirects modes of the lychee check
pass before and after.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The `docs/images` tree is ~218 MB, dominated by ~2,000 screenshots. The PNGs
were already losslessly optimized (oxipng finds no further gains), so the only
lossless lever left is a more efficient container. AVIF is unsupported by
Mintlify, so convert static PNGs to lossless WebP (pixel-identical, universally
supported).
Encoded each PNG with `cwebp -lossless -q 100 -m 6`, keeping the WebP only when
it is smaller than the source (19 PNGs where WebP was larger are left as-is),
and rewrote every reference across English and all locale pages.
converted 2042 PNGs: 131.0 MB -> 92.5 MB (-29.4%)
images/ tree: 218 MB -> 179 MB
3737 text files updated; internal-link check passes with 0 errors
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brandon Pereira