feat(docs): add hands-on kongctl learning guide

[rspurgeon]

Summary

• add a compact, book-style learning site for kongctl
• organize hands-on Setup, Using kongctl, CLI Configuration, Declarative Configuration, Federated Management, and Extensions chapters
• expand the declarative curriculum with metadata, identity, YAML tag, sync scope, adopt/dump, and schema-discovery guidance
• provide a complete AI Gateway working example from creation through update, reconciliation, sync, and deletion
• support command copy, per-block labels, expandable row-limited code blocks, responsive navigation, dark mode, and local progress
• deploy the branch through GitHub Pages for stakeholder review

Preview

https://kong.github.io/kongctl/

The preview is updated when site-related changes are pushed to how-to. GitHub Pages has one site per repository, so this branch temporarily owns that URL until the work is merged and deployment returns to main.

Validation

• npm --prefix site run check
• npm --prefix site test (11 tests)
• npm --prefix site run build (36 pages)
• npm --prefix site run test:e2e (25 browser tests in GitHub Actions)

[Copilot]

Pull request overview

This PR introduces a new “Learn kongctl” static learning guide site (Astro) inside the repository, including initial hands-on chapters and supporting UX (copy-to-clipboard, responsive navigation, theme toggle, and local progress). It also adds local/CI automation to validate and deploy the site via GitHub Pages.

Changes:

• Add an Astro-based learning site with chapter/lesson routing, layouts, styling, and curriculum loading.
• Add client-side enhancements for lesson navigation/filtering, theme persistence, clipboard copy, and local progress tracking (with unit + E2E tests).
• Add Node tooling + CI workflows to check/test/build and deploy the site to GitHub Pages, plus Makefile targets and tooling updates.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
site/vitest.config.ts	Adds Vitest configuration for unit tests.
site/tsconfig.json	Adds strict TypeScript config for the site.
site/tests/e2e/learning.spec.ts	Adds Playwright E2E coverage for key learning UX flows.
site/src/styles/global.css	Introduces global styling (layout, navigation, code blocks, dark mode, responsiveness).
site/src/scripts/site.ts	Implements client-side initialization (theme, nav, filter, progress, code blocks).
site/src/scripts/progress.ts	Adds localStorage-backed learning progress model helpers.
site/src/scripts/progress.test.ts	Unit tests for progress persistence and recovery.
site/src/scripts/copy.ts	Adds copy-to-clipboard enhancement for code fences with labels/status.
site/src/scripts/copy.test.ts	Unit tests for copy controls and clipboard error handling.
site/src/pages/index.astro	Adds learning guide home page rendering chapters and CTAs.
site/src/pages/404.astro	Adds custom “lesson not found” page for the learning site.
site/src/pages/[chapter]/index.astro	Adds chapter index pages via getStaticPaths().
site/src/pages/[chapter]/[lesson].astro	Adds lesson pages with outline, related links, and pagination.
site/src/lib/urls.ts	Adds base-path aware URL helper for consistent trailing slashes.
site/src/lib/curriculum.ts	Loads/validates chapter definitions + lesson content and computes navigation.
site/src/layouts/BookShell.astro	Adds book-style shell layout with sidebar navigation and progress UI.
site/src/layouts/BaseLayout.astro	Adds shared HTML layout, meta tags, theme bootstrap, and site initialization.
site/src/data/chapters.yaml	Defines initial chapters (installation + declarative configuration).
site/src/content/lessons/installation/install-kongctl.md	Adds “Install kongctl” lesson content.
site/src/content/lessons/declarative-configuration/concepts.md	Adds “Declarative configuration concepts” lesson content.
site/src/content.config.ts	Defines Astro content collection schema/loader for lessons.
site/src/components/PageOutline.astro	Adds “On this page” outline component from markdown headings.
site/README.md	Documents local development, checks, E2E, and lesson authoring guidelines.
site/playwright.config.ts	Adds Playwright config for local/CI E2E runs with preview server.
site/package.json	Adds site dependencies, devDependencies, and scripts (check/test/build/e2e).
site/astro.config.mjs	Adds Astro site/base config and markdown highlighting theme.
site/.prettierignore	Ignores generated/build/test artifact directories for formatting.
README.md	Links main repo README to the new learning guide.
Makefile	Adds convenience targets for building/checking/testing the site.
.tool-versions	Adds Node.js tool version for consistent local/CI tooling.
.gitignore	Ignores Node/Astro/Playwright artifact directories in the repo root.
.github/workflows/site-pages.yaml	Adds GitHub Pages deployment workflow for the site.
.github/workflows/site-checks.yaml	Adds CI workflow to check/test/build + run Playwright E2E on PRs.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 34 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

site/src/scripts/site.ts:81

• toggle is nullable (from querySelector) but is used without a null check inside the click handler (toggle.setAttribute(...)). This can fail TypeScript strict null checks (and is inconsistent with the safe optional chaining used elsewhere in this function).

  toggle?.addEventListener("click", () => {
    const open = !document.body.classList.contains("nav-open");
    document.body.classList.toggle("nav-open", open);
    toggle.setAttribute("aria-expanded", String(open));
    if (backdrop) {

[Copilot]

Pull request overview

Copilot reviewed 32 out of 34 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

site/src/scripts/site.ts:81

• toggle is only conditionally present (querySelector can return null), but it’s dereferenced inside the click handler. With strict TS settings this is a type error, and if the handler ever runs without the element it would throw. Use optional chaining (or a guard) when setting the attribute.

  toggle?.addEventListener("click", () => {
    const open = !document.body.classList.contains("nav-open");
    document.body.classList.toggle("nav-open", open);
    toggle.setAttribute("aria-expanded", String(open));
    if (backdrop) {

site/src/layouts/BookShell.astro:64

• The Full documentation link has a malformed closing tag (</a followed by a standalone >). This will render an extra > character in the header and produces invalid markup.

        <a
          class="header-link"
          href="https://developer.konghq.com/kongctl/"
          >Full documentation <span aria-hidden="true">↗</span></a
        >

site/src/layouts/BookShell.astro:53

• In dark theme, the visible logo (.logo-dark) has an empty alt, while the light logo (with alt="Kong") is display: none. Screen readers will lose the brand text in dark mode. Give the dark logo the same alt text.

          <img
            class="brand-logo logo-dark"
            src={logoDark.src}
            alt=""
            width="116"

site/tsconfig.json:5

• With include: ["**/*"] and a custom exclude, TypeScript will start type-checking files under node_modules/ unless they’re explicitly excluded (because specifying exclude overrides TS’s default excludes). That can significantly slow down astro check / CI. Add node_modules (and generated dirs) to exclude.