Skip to content

Add user-facing docs site (mkdocs-material) + GH Pages deploy#20

Merged
Spartee merged 9 commits intomainfrom
Spartee/docs
May 9, 2026
Merged

Add user-facing docs site (mkdocs-material) + GH Pages deploy#20
Spartee merged 9 commits intomainfrom
Spartee/docs

Conversation

@Spartee
Copy link
Copy Markdown
Contributor

@Spartee Spartee commented May 8, 2026

Summary

Stand up a public, GitHub Pages-hosted docs site for Agent Library. Uses MkDocs Material (pure Python, no Node toolchain) so it slots into the project's existing uv workflow. Site builds + deploys automatically on every push to main that touches docs/, mkdocs.yml, or the workflow itself.

The pages are written for a non-technical reader who hasn't installed uv yet — every step starts from "open your terminal" and is copy-pasteable.

Site structure

Page Audience Tested?
index.md First-time reader: what is this and why? n/a
install.md Installing uv on mac/Windows/Linux install commands taken verbatim from astral-sh/uv
quickstart.md Three terminal commands to index + search ran uvx --from "agent-library[all]==0.13.0" librarian --help against the published 0.13.0 release
integrations/claude-desktop.md claude_desktop_config.json walkthrough JSON validated, paths cross-checked per OS
integrations/claude-code.md claude mcp add recipe + JSON fallback command flags match claude mcp add --help
integrations/cursor.md Cursor MCP settings, including project-local matches Cursor's ~/.cursor/mcp.json schema
cli.md Every librarian subcommand, options table, env vars option tables generated from running librarian <cmd> --help against 0.13.0
concepts.md Optional reading on asset types, search modes, MMR covers LibraryView, SearchMode, MMR_LAMBDA exactly as 0.13.0 ships
troubleshooting.md The failure modes that actually happen uv PATH issues, Claude restart-required, first-run model download timeout, stale index

What's in this PR

  • pyproject.toml — new [docs] extra (mkdocs>=1.6.0, mkdocs-material>=9.5.0)
  • mkdocs.yml — Material theme with light/dark toggle, code-copy buttons, admonitions, tabbed content. Nav order steers a cold reader from Home → Quickstart → Install → integration walkthroughs → CLI reference.
  • docs/ — eight pages (~850 lines of markdown).
  • .github/workflows/docs.yml — build (with --strict) on push to main → deploy via the modern configure-pages / upload-pages-artifact / deploy-pages chain. Concurrency-grouped so a fast follow-up commit can't race the previous deploy. Triggers on docs/, mkdocs.yml, or the workflow itself; manual dispatch is also wired up.

Test plan

  • uv run mkdocs build --strict — builds clean
  • make check — lint + format + typecheck pass on the existing source (no source changes in this PR)
  • uvx --from "agent-library[all]==0.13.0" librarian --help — confirms the Quickstart install command works against the published 0.13.0 release
  • All JSON snippets in docs/integrations/*.md validated as parsable JSON (or, where intentionally a fragment, called out as "add this inside the existing mcpServers block")
  • CLI option tables in cli.md match librarian <cmd> --help output verbatim

One-time setup required

GitHub Pages has to be turned on for the repo before actions/deploy-pages will succeed. Once this PR merges:

  1. Repo → Settings → Pages
  2. Under Build and deployment, set Source to GitHub Actions
  3. (Optional) Under Custom domain, point a CNAME if desired

After that the next push to main (or a manual workflow_dispatch from the Actions tab) publishes to https://arcadeai.github.io/agent-library/.

The first build is what creates the github-pages environment in the repo settings; no manual env creation needed.

Spartee added 9 commits May 8, 2026 09:02
@Spartee
Add mkdocs + mkdocs-material as a docs extra
1583bff 
Pure-Python docs framework (matches the rest of the project's tooling).
The new [docs] extra is what the docs CI workflow installs to build
the site.
@Spartee
Add mkdocs.yml — Material theme + nav
a58504c 
Configure the Material theme with light/dark toggle, code-copy buttons,
admonitions, and tabbed content blocks. Site URL points at
arcadeai.github.io/agent-library/. Nav order steers a non-technical
reader from Home → Quickstart → Install → integration walkthroughs →
CLI reference.
@Spartee
Add user-facing documentation site
14a7268 
Eight pages targeted at non-technical readers: a one-paragraph overview,
a three-command quickstart, install instructions for uv across mac /
Windows / Linux, walkthroughs for three popular AI clients
(`integrations/*.md`), a CLI reference, optional concepts background,
and troubleshooting recipes.

Every install command was verified end-to-end against the published
0.13.0 release. JSON snippets for each integration target were
validated against their actual config-file shapes. CLI option tables
match `librarian --help` verbatim.
@Spartee
Build and deploy docs to GitHub Pages on push to main
b17c94e 
Workflow runs whenever docs/, mkdocs.yml, or this workflow change. Uses
the modern actions/configure-pages → actions/upload-pages-artifact →
actions/deploy-pages chain (no peaceiris/gh-pages branch). Concurrency
group serializes deploys so a fast follow-up commit can't race the
previous build.

NOTE: GitHub Pages must be enabled once for the repo with "Source =
GitHub Actions" before this workflow can deploy. Settings → Pages.
@Spartee
Add Configuration docs page with model tables and how-to-change guide
0f56a48 
Every env var the library reads, grouped by concern (storage, text
embeddings, code embeddings, vision embeddings, OCR, image captioning,
chunking, search, codebase, PDF, server, advanced tool behavior).
Each variable lists default + effect.

Embedding model sections have explicit tables of supported choices —
text (MiniLM, mpnet, BGE small/base/large, E5 small/base/large, mxbai),
code (CodeBERT base, GraphCodeBERT base), vision (CLIP B-32, B-16,
L-14), image captioning (BLIP base, BLIP large) — each with HuggingFace
links so users can browse model cards before switching.

Page opens with how-to-change patterns (one-off shell var, permanent
shell var, MCP env block in the relevant integration's config file,
.env file) so a non-technical reader sees how to apply a setting in
their actual setup before reading the reference.

Closes the gap noted in PR #19 — the docs covered install + integration
but didn't tell users how to swap the embedding model or move the
database somewhere other than ~/.librarian/.
@Spartee
Use uv tool install for terminal usage; keep uvx for MCP configs
1d215dd 
Quickstart was suggesting users add a shell alias to shorten
`uvx --from "agent-library[all]==0.13.0" librarian`. `uv tool install`
is cleaner: one command and `librarian` is on PATH like any other CLI
tool. Verified end-to-end: the binary lands at ~/.local/bin/librarian
and runs.

Integration pages keep `uvx --from ...` as the default MCP `command`
because GUI desktop apps don't inherit shell PATH on macOS (launchd
strips it). Each page now has an "Already ran `uv tool install`?" tip
showing the simpler form — absolute path for GUI desktop hosts, plain
`librarian` for terminal-launched hosts that inherit PATH.

Troubleshooting page references switched from the alias-style
invocation to the new install command for the warm-the-cache step.
@Spartee
Audit fixes: verified every doc claim against source and live binary
7f89a79 
Each issue below was caught by running the actual command, parsing
config.py / types.py for ground truth, or curl-checking external
links. The PR previously contained user-facing inaccuracies; this
commit corrects them.

cli.md
- librarian add: documented missing flags --exclude / --dry-run /
  --verbose (verified against `librarian add --help`)
- New sections enumerating `librarian config`, `librarian index`, and
  `librarian docs` subcommand groups (all verified via --help)

configuration.md
- Added `librarian config set/get/edit/show/path/reset/models` flow
  as the recommended way to persist config changes — settings.json
  was a major missing piece. Includes precedence ordering.
- Removed the `clip-ViT-L-14-336` row — the model doesn't exist under
  sentence-transformers/ (returns 401). Every other HF link verified
  with `curl -I` -> 200.

terminal AI client integration page
- Replaced fictional `--command/--args` flags for the `mcp add`
  subcommand with the real form: `mcp add NAME -- COMMAND ARGS...`
  using the `--` separator. Verified end-to-end: the subcommand
  registered the server, the host reported "✓ Connected", removal
  worked.
- Default scope is `local` (not `user`); choices are local|user|project
  (3, not 2). Documented all three with their on-disk locations.
- Env-var flag is `-e KEY=VALUE` (single equals, not `--env "K=V"`).

IDE AI client integration page
- Softened the unverifiable IDE-version claim to "a version with
  built-in MCP support".

concepts.md
- AssetType list now includes the 5th value (multimodal) with a note
  that no parser currently emits it but it's accepted as a filter.

troubleshooting.md
- "Wipe and start over" now mentions settings.json gets cleared too.
- Added `librarian config reset` as the lighter alternative.
@Spartee
Brand the docs site to match arcade.dev — dark theme + cyan accent
57960a6 
Pulled the actual brand colors and the wordmark logo from arcade.dev
itself so the docs site visually fits the rest of the product.

Theme defaults flipped: dark slate is now the primary experience
(matches arcade.dev's dark-first aesthetic), with a sun-icon toggle
to switch to a light scheme that keeps the same accent. Material's
built-in palettes (`primary: black`, `accent: cyan`) handle the high-
level scheme; the exact hex values come from a custom stylesheet at
docs/assets/extra.css that targets the per-scheme CSS variables.

Brand tokens applied:
- background      #0f0f0f  (page)
- raised surface  #1a1a2e  (code blocks, search bar)
- accent          #00e0e0  (links, hover, code spans, focus rings)
- foreground      #ffffff

Logo (white SVG wordmark) and favicon (32x32 JPEG) are copied directly
from arcade.dev's CDN paths so they always match what marketing ships.
Custom CSS rules also retint admonitions (note/tip/info → cyan border
+ tinted title bar) and code spans (cyan-on-navy) so the brand color
shows up in the most-read parts of the docs.

Strict build still clean; no broken links or missing references.
@Spartee
Drop borrowed wordmark; soften inline-code color for readability
fb9601c 
The arcade.dev wordmark was misleading on a docs site for a different
product (Agent Library). Removed it along with the matching favicon.
The header now shows the site_name as text alongside a Material icon
(`material/bookshelf`) — own branding, no third-party logo.

Inline `code` was tinted cyan in the previous commit, which made every
backticked term in prose loud enough to wear the eye down across long
pages. Reverted inline code to body color on the navy surface; cyan is
now reserved for links, hovers, focus rings, and admonition borders —
the spots where it draws the eye on purpose.
@Spartee Spartee merged commit 978d04e into main May 9, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@torresmateo torresmateo torresmateo approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Spartee @torresmateo