docs: a documentation site at openblox.sh - #14
Merged
Merged
Conversation
Everything lived in README.md and ARCHITECTURE.md, which were carrying the pitch, the quick start, the security model and the limitations at once for audiences that want different things. Five pages, built with mkdocs-material and deployed to GitHub Pages: home, quick start, security model, the image contract, contributing. The security model gets its own page rather than a README section, because it is the page that decides whether someone adopts a sandboxing library. It states the threat model, what is isolated and how, and — the part usually left out — what is NOT claimed: gVisor is not a hypervisor, side channels are not addressed, revocation is best-effort. It also names the caller as the weakest link in a default deployment and links the two issues tracking that. The image contract was folklore that surfaced as a broken preview. It is now a page: a shell, a non-root user, and nc-or-python3. CI builds on pull requests without deploying, so a broken docs build is a red check rather than a broken site. `mkdocs build --strict` turns a dead internal link into a failure instead of shipping it. Emits llms.txt: a large share of readers are agents, and this project's subject matter is running the code they write. Docs are markdown in the repository, so a behaviour change and its documentation move in the same pull request.
main now requires Lint, Test, Integration Tests and the commit-message check to pass before merge. A skipped check never reports a conclusion, so with paths-ignore in place a docs-only pull request would sit forever with four required checks pending and no action available to its author. Dropping the filter costs a couple of CI minutes on documentation changes. A category of pull request that silently cannot land costs more. Side effect worth knowing: Release fires on green CI, so it now also runs for docs-only commits. It is a no-op there — `docs:` does not bump a version under conventional commits — but it will appear in the run list where it previously did not.
Closed
Lutherwaves
added a commit
that referenced
this pull request
Aug 17, 2026
* docs: a documentation site at openblox.sh Everything lived in README.md and ARCHITECTURE.md, which were carrying the pitch, the quick start, the security model and the limitations at once for audiences that want different things. Five pages, built with mkdocs-material and deployed to GitHub Pages: home, quick start, security model, the image contract, contributing. The security model gets its own page rather than a README section, because it is the page that decides whether someone adopts a sandboxing library. It states the threat model, what is isolated and how, and — the part usually left out — what is NOT claimed: gVisor is not a hypervisor, side channels are not addressed, revocation is best-effort. It also names the caller as the weakest link in a default deployment and links the two issues tracking that. The image contract was folklore that surfaced as a broken preview. It is now a page: a shell, a non-root user, and nc-or-python3. CI builds on pull requests without deploying, so a broken docs build is a red check rather than a broken site. `mkdocs build --strict` turns a dead internal link into a failure instead of shipping it. Emits llms.txt: a large share of readers are agents, and this project's subject matter is running the code they write. Docs are markdown in the repository, so a behaviour change and its documentation move in the same pull request. * ci: run CI on every pull request, without path filters main now requires Lint, Test, Integration Tests and the commit-message check to pass before merge. A skipped check never reports a conclusion, so with paths-ignore in place a docs-only pull request would sit forever with four required checks pending and no action available to its author. Dropping the filter costs a couple of CI minutes on documentation changes. A category of pull request that silently cannot land costs more. Side effect worth knowing: Release fires on green CI, so it now also runs for docs-only commits. It is a no-op there — `docs:` does not bump a version under conventional commits — but it will appear in the run list where it previously did not.
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.
Closes #13.
Everything lived in
README.mdandARCHITECTURE.md, which were carrying the pitch, the quick start, the security model and the limitations at once — for audiences that want quite different things.The site
Two pages worth reviewing properly
The security model gets its own page rather than a README section, because it is the page that decides whether someone adopts a sandboxing library. It states what is isolated and how — and the part usually left out: gVisor is not a hypervisor, side channels are not addressed, revocation is best-effort, capacity planning is yours. It also names the caller as the weakest link in a default deployment and links #2 and #6.
The image contract was folklore that surfaced as a broken preview. It is now written down: a shell, a non-root
USER, andnc-or-python3.Deploy
main→ build and deploy to Pagesmkdocs build --strictturns a dead internal link or a page missing from the nav into a failure instead of shipping itEmits
llms.txtandllms-full.txt— a large share of readers are agents, and this project's subject matter is running the code they write.Verified
Built locally with the exact command CI runs (
mkdocs build --strict): clean,CNAMEships in the artifact, bothllmsfiles generate. Every pinned action SHA checked to resolve.DNS and Pages are already configured — apex A records point at GitHub (grey-clouded so the certificate can issue),
wwwis a CNAME toblox-eng.github.io, and the custom domain is bound. Merging this is what puts content behind it.Deliberately not doing
No
mikeversioning. At one released version it is gh-pages complexity for nothing; easy to add when there is a v0.2 whose docs differ.