Placeholder Images for Markdown Documentation

Published March 11, 2026

Documentation often needs images before the feature is screenshot-ready. API docs need example response previews, README files need hero images, and tutorial pages need step-by-step screenshots. Placeholder images fill these gaps with correctly sized, labeled files that communicate intent while the real content is in progress.

Using placeholders in GitHub README files

GitHub renders Markdown images inline. You can reference a committed placeholder file by relative path, and it will display in the README preview on GitHub. This is useful for showing layout examples, component previews, or architecture diagrams that haven't been created yet.

The PlacePack label in each image communicates what belongs there — `screenshot:1200x800` or `diagram:800x600` — so readers understand the intent even though the real asset hasn't been added yet.

![App screenshot](docs/images/screenshot_1200x800.png)

![Architecture diagram](docs/images/diagram_800x600.png)

Placeholder images in documentation sites

Documentation generators like Docusaurus, VitePress, and MkDocs support Markdown image syntax and render images in the built site. Placeholder images work the same way as in a README — reference the committed file by path.

For documentation that uses MDX, you can also import the image and use it as a React component prop. This gives you more control over sizing and lazy loading.

Sizing images for documentation layouts

Documentation sites typically have a content column between 700 and 900 pixels wide. Images wider than the column are scaled down, which can blur them or add unexpected padding. Generate placeholders at the exact content width to match the rendered output.

Common documentation image sizes:

- **Full-width screenshot**: 800×500 or 900×560 - **Inline diagram**: 600×400 - **Icon or badge**: 120×40 - **Code output preview**: 700×200

Using the PlacePack API for dynamic docs

For documentation that generates content dynamically — like auto-generated API reference pages — you can use the PlacePack REST API to embed placeholder images by URL. The API returns a stable image for any given spec, so the same URL always produces the same placeholder.

This is a good fit for API documentation tools like Swagger UI or Redoc where you want to show example response images without committing files.

![Example response](https://placepack.top/api/v1/response:800x400.png?bg=1E293B&text=94A3B8)

Replacing placeholders with real content

When the real screenshots or diagrams are ready, replace the placeholder file at the same path. Because the filename already describes the content and dimensions, you know exactly which real asset to create. The Markdown references don't need to change — only the file content does.

FAQ — Frequently asked questions

Can I use PlacePack API URLs directly in Markdown?

Yes. The API returns raw image bytes with the correct Content-Type header. Markdown renderers and browsers will display the image inline. Note the 30 req/min rate limit for high-traffic pages.

What format should I use for documentation images?

PNG for screenshots and raster content. SVG for diagrams and icons — SVGs scale perfectly at any screen density and are much smaller in file size.

How do I keep placeholder images from bloating my repo?

PlacePack generates small, optimized files. A typical 800x500 placeholder PNG is under 5 KB. For very large docs with many images, consider Git LFS.

Related guides

• Placeholder Images for React Native Development →
• Placeholder Images for WordPress Theme Development →
• Placeholder Images for Responsive Web Design Testing →