Skip to content

docs: clear navigation audit findings and audit redirect coverage #394

Description

@dangrondahl

Phase 0 of #393. No structural change, no page moves. Merge this whatever we decide about the rest.

What's wrong

python3 scripts/audit_navigation.py reports 30 advisory shape findings: 8 single-child groups, 10 Title Case labels, 3 groups nested deeper than the 2-container limit. Separately, one internal link is broken and the redirect coverage for externally-referenced URLs has never been checked.

Why it matters

Two of these findings are load-bearing for the restructure. Phase 1 renames tabs and groups, and a rename lands on top of existing Title Case inconsistency, so the casing question gets decided once here instead of per-group later. The single-child groups are the shape Phase 1 dissolves anyway.

The redirect audit matters on its own: ~20 docs URLs are compiled into released CLI binaries and can never be updated. If any of them 404 today, customers on older CLIs are already hitting dead ends and we do not know.

Tasks

  • Sentence-case the 10 Title Case labels. Decide the & convention once (Users & roles is the existing precedent).
  • Dissolve the 8 single-child groups: Managing Custom Attestation Types, FAQ, Evaluation, Multi-flow workflows, Controls, Repositories, Reference > GitHub Action Reference > GitHub Action, Reference > Terraform Reference > Provider, List Resources, Helm Charts.
  • Flatten the 3 over-deep groups: Tutorials > Security > Detecting Terraform drift, Implementation Guide > Phase 2 > Plan Organizational Structure > Naming Conventions, Reference > Helm Reference > Helm Charts > Kubernetes Reporter.
  • Fix the broken internal link to /getting_started/service-accounts in tutorials/working_with_controls.mdx. It has a redirect to /getting_started/authenticating_to_kosli, but mint broken-links does not follow redirects, so the link must be rewritten to the real target.
  • Audit that every URL embedded in a released CLI binary resolves. Generate the list with:
    grep -rhoE 'docs\.kosli\.com/[a-zA-Z0-9_/#.-]+' ../cli --include="*.go" --include="*.gotmpl" | sort -u
  • Same for kosli-dev/server (--include="*.py"), ~20 more URLs including the anchor /getting_started/environments/#snapshoting-an-environment.
  • Add a config/redirects.json entry for anything in either list that does not resolve.

URL impact

  • No page files move — nav-only change, no redirects needed for the label work
  • Page files move

Redirects may be added for already-broken external URLs, but no existing URL changes.

Out of scope

  • Do not restructure Reference > CLI Reference. Single-child groups like kosli allow reflect the CLI's real command tree and are generated by scripts/update-cli-nav.py.
  • Do not rename the Reference tab or its CLI Reference menu item. update-cli-nav.py:154-158 hard-codes both and exits 1 without them.
  • The Helm Charts and Kubernetes Reporter groups can be flattened in navigation, but the pages themselves are generated from chart templates in kosli-dev/cli.

Verification

  • python3 scripts/audit_navigation.py — shape findings reduced, integrity clean
  • python3 scripts/audit_navigation.py --check — exit 0
  • python3 -m pytest tests/ — navigation integrity test passes
  • mint broken-links — zero broken links, including the service-accounts one
  • Every URL in the CLI and server lists resolves (spot-check a sample in the preview deploy)

Activity

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

    contentWriting, adding, or updating doc pagesenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions