Repository files navigation

This repository contains the image documentation for each of the Docker Official Images. Seedocker-library/official-images for more information about the program in general.

All Markdown files here are run throughtianon's fork ofmarkdownfmt, and verified as formatted correctly via GitHub Actions.

1. What is this?
   1. Table of Contents
2. How do I update an image's docs
3. How do I add a new image's docs
4. Files related to an image's docs
   1. folder<image name>
   2. README.md
   3. content.md
   4. get-help.md
   5. github-repo
   6. license.md
   7. logo.png
   8. maintainer.md
   9. metadata.json
   10. README-short.txt
   11. compose.yaml
5. Files for main Docs repo
   1. update.sh
   2. markdownfmt.sh andymlfmt.sh
   3. .template-helpers/generate-dockerfile-links-partial.sh
   4. .template-helpers/
6. Scripts unrelated to templates
   1. generate-repo-stub-readme.sh
   2. push.pl andpush.sh
7. Issues and Contributing

Edit thecontent.md for an image; not theREADME.md as it's auto-generated from the contents of the other files in that repo. To see the changes to theREADME.md, run./update.sh myimage from the repo root, but do not add theREADME.md changes to your pull request. See alsomarkdownfmt.sh pointbelow.

After opening your Pull Request the changes will be checked by an automatedmarkdownfmt.sh before it can be merged. A common issue is incorrect spacing such as with two lines missing an empty line between them (double-spaced).

• Create a folder for my image:mkdir myimage
• Create aREADME-short.txt (required, 100 char max)
• Create acontent.md (required)
• Create alicense.md (required)
• Create amaintainer.md (required)
• Create agithub-repo (required)
• Create ametadata.json (required)
• Add alogo.png (recommended)

Optionally:

• Run./markdownfmt.sh -l myimage to list any files that are non-compliant totianon/markdownfmt.
  Any files in the list will result in a failed build during continuous integration.
  • run./markdownfmt.sh -d myimage to see a diff of changes required to pass.
• Run./update.sh myimage to generatemyimage/README.md for manual review of the generated copy.
  Note: do not actually commit theREADME.md file; it is automatically generated/committed before being uploaded to Docker Hub.

This is where all the partial (e.g.content.md) and generated files (e.g.README.md) for a given image reside, (e.g.golang/). It must match the name of the image used indocker-library/official-images.

This file is generated usingupdate.sh. Do not commit or edit this file; it is regenerated periodically by a bot.

This file contains the main content of your image's long description. The basic parts you should have are a "What Is" section and a "How To" section. The following is a basic layout:

#What is XYZ?// about what the contained software is%%LOGO%%#How to use this image// descriptions and examples of common use cases for the image// make use of subsections as necessary

This file is an optional override of the defaultget-help.md. This is the content of the "Where to get help" part of the "Quick reference" at the top of the generated README. We recommend linking to the best places for community support like forums, chat rooms, or mailing lists.

This file should contain the URL to the GitHub repository for the Dockerfiles that become the images. The file should be in a single line ending in a newline with no extraneous whitespace. Only one GitHub repo per image repository is supported. It is used in generating links. Here is an example forgolang:

https://github.com/docker-library/golang

This file should contain a link to the license for the main software in the image. Here is an example forgolang:

View[license information](http://golang.org/LICENSE) for the software contained in this image.

Logo for the contained software. While there are not hard rules on formatting, most existing logos are square or landscape and stay within a few hundred pixels of width. Alternatively, alogo.svg can be used instead, but only one logo file will apply. To use it withincontent.md, put%%LOGO%% as shown above in the basiccontent.md layout.

The image is automatically scaled to a 120 pixel square for the top of the Docker Hub page and Hub search results.

This file should contain a link to the maintainers of the Dockerfile.

This file contains data about the repo for Docker Hub. The minimum file is defined below../metadata.sh [repo-name] must be used to correctly format it (use-w to apply its suggested format changes). Only three sorted unique Docker Hub categories are allowed.metadata.json in the root contains the list of categories to choose from. See descriptions for the categories on theDocker docs site.

{"hub": {"categories": []    }}

This is the short description for the Docker Hub, limited to 100 characters in a single line.

Go (golang) is a general purpose, higher-level, imperative programming language.

This optional file contains a small, workingCompose file showing off how to use the image. To use thecompose.yaml, add%%COMPOSE%% to thecontent.md and this will embed the YAML.

Other official images may be referenced within the YAML to demonstrate the functionality of the image, but no images external to the Docker Official Images program may be referenced.

This is the main script used to generate theREADME.md files for each image. The generated file is committed along with the files used to generate it. Accepted arguments are which image(s) you want to update or no arguments to update all of them.

This script assumesbashbrew is in yourPATH (for scraping relevant tag information from the library manifest file for each repository).

These two scripts are for verifying the formatting of Markdown (.md) and YAML (.yml) files, respectively.markdownfmt.sh uses thetianon/markdownfmt image andymlfmt.sh uses thetianon/ymlfmt image.

This script is used byupdate.sh to create the "Supported tags and respectiveDockerfile links" section of each generatedREADME.md from the information in theofficial-imageslibrary/ manifests.

The scripts and Markdown files in here are used in building an image'sREADME.md file in combination with its individual files.

This is used to generate a simpleREADME.md to put in the image's repo. We use this in Git repositories withinhttps://github.com/docker-library to simplify our maintenance, but it is not required for anyone else. The only argument is the name of the image (or repo), likegolang and it then outputs the readme to standard out.

These are used by us to push the actual content of the READMEs to the Docker Hub as special access is required to modify the Hub description contents. TheDockerfile is used to create a suitable environment forpush.pl.

If you would like to make a new Official Image, be sure to follow theguidelines.

Feel free to make a pull request for fixes and improvements to current documentation. For questions or problems on this repo come talk to us via the#docker-library IRC channel onLibera.Chat or open up an issue.