Skip to content

docs: the CI runner image link lands on a tab the reader is not on #441

Open

Description

@claude

tutorials/trail_summaries_in_ci.md links twice to a heading that lives inside a non-default <Tab>. A reader who follows either link lands on /integrations/ci_cd showing GitHub Actions content, with no Alpine section anywhere on screen.

The links

tutorials/trail_summaries_in_ci.md:79:

Use the Kosli Alpine CI runner image so kosli, git, and curl are preinstalled and no before_script setup is needed

tutorials/trail_summaries_in_ci.md:100:

see CI runner image (Alpine) for the build steps

The second one is load-bearing: the tutorial tells the reader to replace an image tag "with whatever tag you pushed when you built the Alpine image", and this link is where the build steps are.

The target

integrations/ci_cd.md wraps almost all of its content in a <Tabs> block opened at line 17. ### CI runner image (Alpine) is at line 89, inside <Tab title="GitLab"> (opened at line 70). The first and therefore default tab is <Tab title="GitHub"> at line 18.

17:  <Tabs>
18:   <Tab title="GitHub" icon="github">
...
70:  <Tab title="GitLab" icon="gitlab">
...
89:  ### CI runner image (Alpine)

The anchor target is inside collapsed tab content, so the browser has nothing visible to scroll to. The reader sees the top of the CI/CD page with the GitHub tab selected.

mint broken-links will not catch this — the page exists and the heading exists.

Why it matters

trail_summaries_in_ci is a GitLab-flavoured tutorial, so by the time the reader follows this link they already know they are on GitLab; the page just does not show them GitLab. It is also one of the pages with no inbound links of its own (#440), so a reader who ends up stuck here has no obvious way onward.

What a fix looks like

Pick one:

  • Make the link text say which tab to open, e.g. "see CI runner image (Alpine) under the GitLab tab on the CI/CD page", and keep the anchor as a best-effort target.
  • Move the Alpine runner image section out of the <Tabs> block. It is a container image with kosli, git and curl preinstalled — not actually GitLab-specific — so a top-level section on integrations/ci_cd would serve the Azure DevOps, Bitbucket, CodeBuild, CircleCI and Teamcity tabs too.

The second is the better fix if the image really is CI-agnostic.

Also worth a look while in there

administration/cloud_capture/getting_started.md has two ### Excluding resources headings, at line 46 (inside <Tab title="AWS">) and line 70 (inside <Tab title="GCP">). administration/cloud_capture/overview.md:44 links to #excluding-resources. The AWS one is the intended target and it is in the default tab, so this one probably resolves correctly today — but it depends on which of two identical slugs the renderer picks, which is not something to leave to chance. Renaming the GCP heading (it currently reads only "Support for excluding resources is coming soon") removes the ambiguity.

URL impact

Moving the Alpine section within integrations/ci_cd.md does not move the page file, so no config/redirects.json entry is needed. It does not change the #ci-runner-image-alpine anchor either, as long as the heading text is unchanged.

Note that /integrations/ci_cd is the single most-referenced docs URL in released CLI binaries (about 15 references per #393), and /integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables is linked from roughly 30 generated client_reference/ pages. That anchor is at line 13, above the <Tabs> block, and must stay there.

Evidence

$ grep -rn "ci_cd#ci-runner-image-alpine" --include=*.md --include=*.mdx .
$ grep -nE '^\s*#|<Tab ' integrations/ci_cd.md
$ grep -n '^#' administration/cloud_capture/getting_started.md

Found by the monthly doc-structure audit, step 2 (cross-reference rot — anchors).

Activity

  1. added
    bugSomething isn't working
    contentWriting, adding, or updating doc pages
    on Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingcontentWriting, adding, or updating doc pages

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions