Docs & Code Guide

Embed a diagram in a Docker Hub overview: the second README nobody updates

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

A Docker Hub repository has a full description that renders as Markdown, and it is not your README. It is a separate field stored on Docker Hub, edited in a web form or pushed by CI, capped at 25,000 bytes, with a 100 character short description alongside it. That separation is why so many image pages describe a container two years out of date, and it is the reason an image address beats a committed picture here.

Try it free
6 min readFor teams publishing container images to Docker Hub

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

155/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The overview is a copy, and copies drift

The full description lives on Docker Hub, not in the repository. Someone pasted the README into that form once, and unless the team wired up a sync, it has been diverging from the repository ever since. peter-evans/dockerhub-description exists for exactly one reason, pushing README.md into that field on each release, and an action with that single job and that many users is a measurement of how often the two drift.

Wire the sync if you can: a CI step that updates the description on each release keeps the words honest, and several of those tools can also expand relative links into absolute ones on the way through. Then the only remaining question is what the images point at.

Two limits are worth knowing before you write, and they are the ones that action documents because it has to truncate against them: the full description is capped at 25,000 bytes, and the short description shown in search results at 100 characters. A long README with embedded base64 assets hits the first one surprisingly fast.

Absolute image addresses, always

Docker Hub renders Markdown with no repository context, so a relative path resolves to nothing, exactly as on npm and PyPI. Any image in the overview needs a full https address, whether it points at a raw file in the repository or at a rendered diagram.

Given that constraint, the choice is between an address that returns a file frozen at some commit and an address that returns the current drawing. For a container image, whose readers are usually deciding how it will fit into their stack, current wins. The overview text changes at release cadence; the picture can change the day the architecture does.

## What this image runs

![Container architecture](https://datadef.io/api/embed/my-service-a1b2c3d4?width=1600&height=900)

Ports, volumes and environment variables are documented below.

What a container page reader actually needs to see

Not the internals of the application. The useful diagram on an image page is the deployment shape: the container itself, the ports it listens on, the datastores and queues it expects to reach, the sidecars or companion containers it assumes, and the external services it calls at runtime.

That is a picture the compose file or the Kubernetes manifests already imply, which is why generating it from the repository beats drawing it by hand. Related material on that path is in a living diagram from Docker Compose and a living diagram from Kubernetes manifests.

Keep the render wide and light on nodes. An image page is skimmed, often by someone comparing three candidate images in three browser tabs.

Rendering details for the overview column

The endpoint accepts format png or jpeg, width from 600 to 4000, height from 400 to 4000, and scale from 1 to 3, defaulting to 1600 by 1000 at 2x. PNG is the right default for a diagram; the JPEG option exists for renders that carry a photographic background.

Caching is handled at the origin: Cache-Control max-age=300 with a long stale-while-revalidate, plus an ETag derived from the canvas state, so an edited diagram appears within minutes and repeat readers get a 304 rather than a re-render.

Interactive views do not apply here. Docker Hub renders sanitized Markdown, so an iframe is not an option; use the image plus a plain link for anyone who wants to zoom.

Public means public

The embed address resolves only while the project is shared publicly, which is the correct posture for a public image page and the wrong one for internal topology. Keep hostnames, account ids and internal service names out of a diagram destined for Docker Hub. See sharing documentation.

Keeping the picture matched to the image you ship

Connect the repository read-only from GitHub, GitLab or Azure DevOps, choose a branch or tag, and the daily sync regenerates the diagram and an architecture.md. Pointing the sync at the tag you release from is the closest thing to a version-accurate picture without committing one per tag.

For an infrastructure repository the parser is opinionated about what does not belong on a page like this. Resource types classified as wiring never become a box: role assignments, grants, IAM members, policy attachments, secrets and certificates, along with every resource from the random, null, local, time, tls, archive, template and external providers. They are counted rather than drawn, so the architecture document reports a line like eight grants, six permissions, four role assignments while the picture stays a picture. Attributes that name a container, a resource group or a virtual network, are drawn as nesting rather than as arrows, which is why the output has zones instead of a hairball.

When the container is part of a larger platform, one diagram of the platform, embedded from the same address in the Docker Hub overview, the repository README and the docs site, beats three drawings that disagree. See repo to diagram.

FAQ

Does my repository README automatically appear on Docker Hub?

No. The full description is a separate field stored on Docker Hub, edited on the site or pushed through the API by a CI step. Without a sync it diverges from the repository README over time, which is why dedicated GitHub Actions exist to keep the two aligned.

Why is an image in my Docker Hub description not rendering?

Relative paths do not resolve, because the description is rendered without any repository context. Use a full https address. Also check the length, since the full description is limited to 25,000 bytes and content beyond that is not stored. A third cause is an http address, which every current browser blocks as mixed content on an https page.

How long can a Docker Hub description be?

The full description is limited to 25,000 bytes and the short description to 100 characters. Referencing images by URL rather than embedding encoded data keeps a documentation-heavy overview well inside the limit. Sync tools that push a README into that field truncate against the same ceiling, so an overview that grows past it loses its tail quietly rather than failing loudly.

Can a Docker Hub overview show an interactive diagram?

No. The overview is sanitized Markdown, so iframes and scripts are removed and only an image can render. Pair the image with a plain link to an interactive view for readers who want pan and zoom. The image can still be live, because Docker Hub stores your markdown rather than your pictures, so an address renders whatever it returns when somebody reads the page.

What should the diagram on a container image page show?

The deployment shape rather than the code: the container, the ports it exposes, the databases and queues it expects, companion containers, and the external services it calls. That is what a reader comparing candidate images needs in order to decide.