Skip to content

docs: Material for MkDocs site with GitHub Pages deploy#11

Merged
OsherElhadad merged 4 commits into
mainfrom
docs/mkdocs-site
Jul 21, 2026
Merged

docs: Material for MkDocs site with GitHub Pages deploy#11
OsherElhadad merged 4 commits into
mainfrom
docs/mkdocs-site

Conversation

@OsherElhadad

Copy link
Copy Markdown
Collaborator

What

A public documentation website for context-guru, in the style of adk.dev — built with Material for MkDocs, reusing the existing Markdown docs in place, and deployed to GitHub Pages via a new Actions workflow.

Highlights

  • Marketing homepage (custom overrides/home.html): hero, copyable run command, feature cards for the three guarantees + integration modes, a before→after compaction demo, and a benchmark highlight.
  • ADK-style nav: Get Started, Concepts, Components (overview + 13 per-component pages + the DSL engine), How-to Guides, Examples, Benchmarks, Reference, Community.
  • Visualizations: native Mermaid architecture diagrams, MathJax for the phi_evict Φ formula, and an interactive Chart.js benchmark chart on the Results page (real SWE-bench numbers).
  • Claude Code integration: how-to/use-with-claude-code.md (one-env-var setup) + scripts/with-guru.sh helper; fixed the stale scripts/cc-demo.sh to the current proxy interface.
  • Doc/code drift fixed: documented the toon component (was missing from components.md).
  • Deploy: .github/workflows/docs.yaml builds with mkdocs build --strict on PRs and deploys Pages from main; decoupled from the Go CI.

Preview locally

pip install -r requirements-docs.txt
mkdocs serve

Verified

  • mkdocs build --strict passes with zero warnings.
  • Deterministic components sanity-checked: format+toon via POST /compact on the committed sample is byte-identical to the expected output.

Notes for merge

  • Enable GitHub Pages with Source = "GitHub Actions" in repo settings so the deploy job can publish.
  • The benchmark chart data is inlined in docs/javascripts/charts.js (marked with a ponytail: comment) rather than auto-synced to the results CSV.
  • IBM Bob integration lands in a follow-up PR (needs a small proxy feature ported from winnow).

Osher-Elhadad added 4 commits July 21, 2026 13:04
Add a public documentation website in the style of adk.dev, built with
Material for MkDocs and reusing the existing Markdown docs in place.

- Marketing homepage (hero, install command, feature cards, before->after
  demo, benchmark highlight) via a custom home.html override.
- ADK-style nav: Get Started, Concepts, Components (overview + 13
  per-component pages + DSL engine), How-to Guides, Examples, Benchmarks,
  Reference, Community.
- Native Mermaid diagrams, MathJax for the phi_evict formula, and an
  interactive Chart.js benchmark chart on the Results page.
- Fix components.md drift: document the toon component.
- docs.yaml builds with --strict on PRs and deploys Pages from main.

Cross-repo links in reused docs rewritten to absolute GitHub URLs so they
resolve on the published site. check-yaml runs with --unsafe for mkdocs.yml.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Osher-Elhadad <Osher.Elhadad@ibm.com>
- how-to/use-with-claude-code.md: one-env-var integration, gateway mode,
  project .claude/settings.json, and verification via /stats.
- scripts/with-guru.sh: minimal-effort wrapper that starts the proxy and
  runs any base-URL-swappable agent through it (e.g. with-guru.sh agent -- claude).
- Fix scripts/cc-demo.sh to the current context-guru-proxy interface
  (the old lab-cx proxy --extract-* flags no longer exist).

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Osher-Elhadad <Osher.Elhadad@ibm.com>
Merge origin/main into the docs branch and run gofmt across the repo — the
kagenti->rossoctl module rename string-replaced import paths without re-sorting,
leaving the whole tree gofmt-dirty and failing `make lint` on every PR. gofmt
re-orders the imports (github.com/maximhq now sorts before github.com/rossoctl).

Also retarget the new docs to the moved repo: kagenti/context-guru ->
rossoctl/context-guru, the AuthBridge plugin repo -> cortex, and the Pages URL.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Osher-Elhadad <Osher.Elhadad@ibm.com>
@OsherElhadad
OsherElhadad merged commit 3dd66e9 into main Jul 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant