# docker-library/docs: the source files behind every Docker Official Image description > This repository holds the per-image documentation that becomes the Docker Hub long description. It is a build system for text, not a place to read docs, and its rules are stricter than most contributors expect. **docker-library/docs** — Documentation for Docker Official Images in docker-library - Repository: https://github.com/docker-library/docs - Website: https://github.com/docker-library/official-images - Stars: 5,290 · Forks: 2,234 - Language: Shell - License: MIT - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/docker-library-docs ## What docker-library/docs actually is The README opens by stating that the repository contains the image documentation for each of the Docker Official Images, and points to docker-library/official-images for information about the program itself. That split matters. The official-images repository carries the metadata that decides which images exist; this repository carries the prose that Docker Hub shows on each image page. The audience is narrow. You are in scope if you are writing or fixing the description of an image that is already part of the program, or if you are preparing the documentation files for a new image. You are out of scope if you want a documentation generator for your own project, or a place to host long-form guides. Nothing here builds a site: it assembles a single README.md per image from a handful of small source files. The top-level layout reflects that. Alongside README.md, LICENSE, Dockerfile and a set of scripts, the repository is mostly a flat list of directories named after images: alpine/, bash/, golang/, postgres-style entries and dozens more. Each directory is one Docker Hub page. ## The files that make up one image page A single image folder is a small assembly line. The README lists six required files: README-short.txt (100 characters maximum), content.md, license.md, maintainer.md, github-repo and metadata.json. logo.png is recommended rather than required, and logo.svg can be used instead, but only one logo file applies. content.md is the body of the page. The README suggests a basic layout of a What Is section and a How to use this image section, with %%LOGO%% marking where the logo is injected. compose.yaml is optional and is embedded by placing %%COMPOSE%% in content.md; the README adds a constraint that other official images may be referenced in that YAML but no images external to the Docker Official Images program may be. github-repo holds a single line with the URL of the repository containing the Dockerfiles, with a trailing newline and no extra whitespace, and only one repository per image is supported. metadata.json carries Docker Hub data, and the README states that ./metadata.sh [repo-name] must be used to format it correctly, with -w applying the suggested changes. Only three sorted unique Docker Hub categories are allowed, chosen from the list in the root metadata.json. The generated README.md is deliberately not a source file. The README says to edit content.md and not README.md, because the latter is auto-generated from the other files and is regenerated periodically by a bot. ## Installing the toolchain and generating a README There is no package to install. The scripts in this repository are meant to be run from a checkout, and the repository ships a Dockerfile so the toolchain can be built as an image instead of installed on your machine. That Dockerfile starts from perl:5.40-trixie, installs vim and inkscape, sets PERL_CPANM_OPT with a CPAN mirror, and installs App::cpanminus along with Mojolicious and a set of Perl modules. The comment in the file explains that inkscape is present because SVG rendering in ImageMagick looks poor without it. Clone the repository and move into it: ```bash git clone https://github.com/docker-library/docs.git cd docs ``` Suppose you are editing the golang image. You change content.md inside the golang/ directory, then regenerate the README to review the result. The README states that you run this from the repo root and that you must not add the generated README.md changes to your pull request: ```bash ./update.sh golang ``` Before opening a pull request, check formatting. The README gives two modes: -l lists files that are non-compliant with tianon/markdownfmt and -d shows the diff of changes required to pass. ```bash ./markdownfmt.sh -l golang ./markdownfmt.sh -d golang ``` Any file that appears in the -l list will fail the continuous integration build. The README names a common cause: missing blank lines between two lines, described there as double-spaced. If you are adding a brand new image rather than editing one, the README lists the creation steps in order: mkdir myimage, then README-short.txt, content.md, license.md, maintainer.md, github-repo and metadata.json, with logo.png as the recommended extra. ## Where the workflow will bite you The single biggest trap is the generated file. README.md inside an image folder looks like the obvious place to make a correction, and editing it produces a change that the bot will overwrite. The README states plainly not to commit or edit it. If you have already pushed an edit there, the fix is to move the change into content.md and regenerate. Formatting is the second trap, and it is enforced rather than advisory. All Markdown files are run through tianon's fork of markdownfmt and verified via GitHub Actions, so a whitespace-only difference is enough to fail the check. Running markdownfmt.sh -l locally before pushing is the only way to see the failure early. There is also a naming coupling that is easy to miss. The README says the folder name must match the name of the image used in docker-library/official-images. A folder that does not correspond to an image in that repository has nothing to attach to. Finally, the content constraints are tighter than a normal README. README-short.txt is capped at 100 characters on a single line. metadata.json accepts at most three sorted, unique categories. compose.yaml cannot reference images outside the official program. If your documentation needs a diagram, a multi-page structure or third-party example images, this format does not accommodate it. ## How this differs from a general docs generator A tool like MkDocs, Sphinx or Docusaurus treats your Markdown as the source of a site it builds and serves. This repository does the opposite. It treats small fragments as input to a single generated README.md, which is then handed to Docker Hub, where the rendering happens. There is no theme, no navigation, no search index and no output directory you deploy. The practical difference is where control sits. With a docs generator you own the output and can restructure it freely. Here the output format is fixed by the Hub page and by the template helpers in .template-helpers/, including generate-dockerfile-links-partial.sh, which the README lists as part of the template machinery. The scripts generate-repo-stub-readme.sh, push.pl and push.sh sit outside the template path and handle other repository chores. That trade is worth naming. You get a consistent page across hundreds of images and a review process that catches formatting drift, at the cost of a rigid structure and a bot that owns one file in your working tree. ## Maintenance and licence position The repository is not archived, and the last push was on 2026-09-22. Activity here is driven by the images themselves: when an upstream project changes its usage instructions, the corresponding content.md changes with it. There are no releases to track, and the README does not document a versioning scheme for the scripts, so an upgrade is whatever lands on master. Practically, that means the cost of staying current is low but not zero. The formatting rules and the template helpers can change without a release note, and a pull request that was clean last month can fail markdownfmt.sh after a change to the fork. Re-running ./markdownfmt.sh -l myimage before each contribution is the cheap insurance. The repository is MIT licensed, and the Dockerfile in the root is part of that same repository. Note that the licence of this repository is separate from the licences of the software described in each image folder; license.md exists per image precisely because those are different things. The README does not give legal guidance, and nothing here should be read as legal advice. ## Conclusion Adopt it if you maintain or contribute documentation for an image in the Docker Official Images program, because Docker Hub renders your README.md and nothing else. Do not adopt it as a general documentation site generator or as a place to publish your own image's docs outside that program, since the folder name must match an image in docker-library/official-images. Before your first pull request, run ./markdownfmt.sh -l myimage to see which files fail the formatting check and ./update.sh myimage to read the generated README.md, and leave that generated file out of the commit. ## FAQ ### What are the Docker docs in docker-library/docs used for? They supply the long description shown for each Docker Official Image on Docker Hub. Each image folder holds source fragments such as content.md and metadata.json, and update.sh assembles them into a generated README.md. ### Which files do I need to add for a new image in docker-library/docs? The README lists README-short.txt, content.md, license.md, maintainer.md, github-repo and metadata.json as required, with logo.png recommended. It also notes that the folder name must match the image name used in docker-library/official-images. ### Should I edit README.md in an image folder of docker-library/docs? No. The README states that README.md is generated by update.sh, is regenerated periodically by a bot, and must not be committed or edited. Edit content.md and the other source files instead. ### Why did my pull request to docker-library/docs fail the formatting check? All Markdown files are run through tianon's fork of markdownfmt and verified via GitHub Actions. The README names missing blank lines between two lines as a common cause, and suggests running ./markdownfmt.sh -l myimage to list non-compliant files before pushing. ## Sources - [docker-library/docs on GitHub](https://github.com/docker-library/docs) - [Issues](https://github.com/docker-library/docs/issues) - [License: MIT](https://github.com/docker-library/docs/blob/master/LICENSE) - [Project website](https://github.com/docker-library/official-images) - [README](https://github.com/docker-library/docs/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/docker-library-docs