Documentation for Infrastructure Projects like Docker, Podman, Kubernetes #110

Activity

1. moshest commented on Aug 18, 2026

   

   moshest

   on Aug 18, 2026 – with Claude

   Member

   More actions

   Yes please — these would be a great addition, and the directory layout you proposed is exactly right.

   docker/, kubernetes/, podman/, systemd/, each holding a single self-named file:

   registry/docker/docker.yaml
   registry/kubernetes/kubernetes.yaml
   registry/podman/podman.yaml
   registry/systemd/systemd.yaml
   

   That's not a special case for infrastructure projects — it's the existing convention for anything not distributed by a package manager. registry/python/python.yaml and registry/java/java.yaml already work that way. The npm/pip/maven/hex directories are named after the registry the package comes from; when there isn't one, the project's own name is the directory.

   One thing to avoid, because it will bite you. Don't use the versions: + min_version: + git shape in these directories:

   # DON'T do this in docker/ — it will fail
   versions:
     - min_version: "1.0.0"
       source: { type: git, url: ..., docs_path: ... }

   That shape asks a version-discovery API which versions exist before matching them against the range, and only npm, pip, maven and hex have one. Anywhere else it fails with Unsupported registry: docker. I confirmed this against the CLI just now, and it matters more than it looks: one failing definition fails the entire nightly publish run, so it would take every other package down with it.

   Use one of these two instead — both verified working in a scratch docker/ directory:

   # Unversioned — always builds the current docs, published as "latest"
   name: docker
   description: "Docker documentation"
   repository: https://github.com/docker/docs
   
   source:
     type: git
     url: https://github.com/docker/docs
     docs_path: content

   # Versioned by zip — when the project ships docs archives per release
   name: kubernetes
   versions:
     - versions: ["1.31", "1.30"]
       source:
         type: zip
         url: "https://.../v{version}.zip"
         docs_path: "content/en/docs"

   Unversioned is the simpler start, and for these four projects it's probably the right call — the docs track the project rather than being archived per release. Add ref: <branch> if the docs aren't on the default branch.

   Markdown, HTML, AsciiDoc and reStructuredText all index fine, so systemd's man pages should work as well.

   Before opening the PR, check it produces real content:

   pnpm --filter @neuledge/registry registry build docker

   A few hundred sections means docs_path is right; a handful usually means it's pointing at the wrong directory.

   You had to ask because none of this was written down anywhere — the README invites contributions and links to registry/, which had no README of its own. That's fixed in #111, which documents all of the above. Sorry for the friction, and thanks for offering.

   Happy to review the PRs whenever you open them — one per project is easiest, or all four together if you prefer.

   ---

   Generated by Claude Code
2. moshest

   added a commit that references this issue on Aug 18, 2026

   docs(registry): document how to add a package definition (#111)

   ...

   89c4ca7
3. TheRealBecks commented on Aug 19, 2026

   

   TheRealBecks

   on Aug 19, 2026

   Last edited by TheRealBecks

   ContributorAuthor

   More actions

   @moshest I created #113 for Docker as the first to be added documentation. The other PRs will follow
4. moshest commented on Aug 25, 2026

   

   moshest

   on Aug 25, 2026 – with Claude

   Member

   More actions

   All three PRs are merged — thanks for these.

   • docker (Add Docker documentation #113) — 5,040 sections
   • kubernetes (Add Kubernetes documentation #114) — 7,010 sections
   • podman (Add Podman documentation #115) — 1,257 sections

   I built each one locally before merging, since CI doesn't run on fork PRs.

   Closing this — systemd is tracked in #116, and I'll answer there.

   ---

   Generated by Claude Code
5. moshest

   closed this as completedon Aug 25, 2026