docs: add MkDocs Material site deployed to GitHub Page#112
Merged
Conversation
…GET, and batch operations
Extend the HTTP cache API with three new capabilities:
- HEAD /v1/cache/:key — returns X-Cache-* metadata headers (Version,
Origin, Last-Updated, TTL-Ms, Expires-At, Owners, Node) with no body.
Enables fast existence + TTL checks without value transfer.
- GET /v1/cache/:key with Accept: application/json — returns an
itemEnvelope with the same metadata as HEAD plus the base64-encoded
value. Bare curl / octet-stream clients are unaffected.
- POST /v1/cache/batch/{get,put,delete} — bulk operations in a single
round-trip. Each request carries an array; responses carry per-item
status, owners, and error detail. Batch-put supports both UTF-8
string and base64-encoded payloads via value_encoding. Per-item
errors do not fail the whole batch.
Add six unit tests in handlers_test.go pinning the contracts: HEAD
present/missing, Accept-JSON envelope shape, raw bytes back-compat,
mixed-encoding batch-put, batch-get found/missing, and batch-delete
cycle.
Update README and CHANGELOG accordingly.
Set up a full documentation site for HyperCache, built with MkDocs Material and published automatically to GitHub Pages on every push to `main`. - Add `mkdocs.yml` with Material theme, pymdownx extensions, mermaid support, and the include-markdown + glightbox plugins. - Add eight navigated doc pages: landing, quickstart, 5-node cluster tutorial, Helm chart guide, server-binary reference, RFC index, changelog, and distributed-backend architecture stub. The changelog and server-binary pages are included from their canonical sources (CHANGELOG.md / cmd/hypercache-server/README.md) via include-markdown to avoid content drift. - Add `_mkdocs/hooks.py`: a build-time hook that rewrites repo-relative source-code links (e.g. `../pkg/foo.go`) to canonical GitHub URLs, keeping the same markdown valid on both github.com and the Pages site under strict mode. - Add `.github/workflows/docs.yml`: builds with `--strict` on every PR and deploys via `actions/deploy-pages@v4` on pushes to `main`. - Add `docs-build`, `docs-serve`, and `docs-publish` Makefile targets (pyenv-aware, using the `mkdocs` virtualenv). - Relax mdl rules that conflict with MkDocs idioms: MD041 (YAML frontmatter), MD010 (Go tab-in-code-blocks), MD033/MD032 (Material grid-card HTML wrappers). - Update README with a docs badge and a link to the rendered site. - Add MkDocs-related terms to cspell dictionary and ignore the generated `/site/` directory and `_mkdocs/__pycache__/`.
hyp3rd
changed the title
- Add docs/requirements.txt with pinned versions of MkDocs, Material theme, and plugins to ensure reproducible builds locally and in CI - Update docs workflow to install deps from requirements.txt instead of inline package names, and wire `cache-dependency-path` to the new file so pip cache hits are deterministic - Bump actions/upload-pages-artifact and actions/deploy-pages to v5 - Add `_mkdocs/` to the SOURCE_DIR_PREFIXES exclusion list in hooks.py - Add pyenv and venv to the cspell dictionary - Minor formatting fixes (branch list spacing, comment alignment)
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.
No description provided.