Add user-facing docs site (mkdocs-material) + GH Pages deploy#19
Closed
Add user-facing docs site (mkdocs-material) + GH Pages deploy#19
Conversation
Spartee
added a commit
that referenced
this pull request
May 8, 2026
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, L-14-336), image captioning (BLIP base, BLIP large) — each with HuggingFace links so users can browse model cards before switching. Page opens with four how-to-change patterns (one-off shell var, permanent shell var, MCP env block in claude_desktop_config.json / ~/.cursor/mcp.json, .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
added a commit
that referenced
this pull request
May 8, 2026
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/.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
uvworkflow. Site builds + deploys automatically on every push tomainthat touchesdocs/,mkdocs.yml, or the workflow itself.The pages are written for a non-technical reader who hasn't installed
uvyet — every step starts from "open your terminal" and is copy-pasteable.Site structure
index.mdinstall.mduvon mac/Windows/Linuxquickstart.mduvx --from "agent-library[all]==0.13.0" librarian --helpagainst the published 0.13.0 releaseintegrations/claude-desktop.mdclaude_desktop_config.jsonwalkthroughintegrations/claude-code.mdclaude mcp addrecipe + JSON fallbackclaude mcp add --helpintegrations/cursor.md~/.cursor/mcp.jsonschemacli.mdlibrariansubcommand, options table, env varslibrarian <cmd> --helpagainst 0.13.0concepts.mdLibraryView,SearchMode,MMR_LAMBDAexactly as 0.13.0 shipstroubleshooting.mduvPATH issues, Claude restart-required, first-run model download timeout, stale indexWhat'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 modernconfigure-pages/upload-pages-artifact/deploy-pageschain. Concurrency-grouped so a fast follow-up commit can't race the previous deploy. Triggers ondocs/,mkdocs.yml, or the workflow itself; manual dispatch is also wired up.Test plan
uv run mkdocs build --strict— builds cleanmake 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 releasedocs/integrations/*.mdvalidated as parsable JSON (or, where intentionally a fragment, called out as "add this inside the existingmcpServersblock")cli.mdmatchlibrarian <cmd> --helpoutput verbatimOne-time setup required
GitHub Pages has to be turned on for the repo before
actions/deploy-pageswill succeed. Once this PR merges:After that the next push to
main(or a manualworkflow_dispatchfrom the Actions tab) publishes tohttps://arcadeai.github.io/agent-library/.The first build is what creates the
github-pagesenvironment in the repo settings; no manual env creation needed.