Managing Images in Docs-as-Code Repos

Docs-as-code works beautifully for text: Markdown diffs are readable, reviews happen in pull requests, and history shows who changed what and why. Images are the part that goes wrong. A writer drags a 4 MB PNG screenshot from a Retina display into the repository; a product redesign means replacing 300 screenshots, each a new binary that Git keeps forever alongside the old one; files named image (3).png pile up in one folder, some referenced by nothing. Two years in, a fresh clone takes minutes, CI checkouts dominate build time, and nobody knows which images are still in use.

This guide sets up image handling for a documentation repository with about 2,400 images: where images live, size limits enforced before commit, Git LFS versus plain Git, naming and co-location, checks for unused images and missing alt text, and automated screenshots. It is part of Content Workflows for Documentation Teams.

Prerequisites

• A docs repository built by a static generator with an image pipeline (Hugo, Astro, Eleventy).
• Contributors who add images through Git, directly or via a web editor.
• Access to repository settings for LFS and CI.

The Problem in Numbers

The documentation repository's state before cleanup:

Most of the repository's size was old versions of screenshots replaced during two redesigns — history that no build ever used again.

Step 1: Co-locate Images With Pages

Images in one global static/images/ folder lose their context; nobody knows which page uses dashboard-2.png. Moving each image next to the page that uses it — Hugo page bundles, Astro content collection folders, Eleventy directories — makes ownership obvious and deletion safe:

content/guide/install/
  index.md
  install-wizard-step-1.png
  install-wizard-step-2.png
content/guide/configure-sso/
  index.md
  sso-settings.png

Names describe the content (sso-settings.png), not the moment it was taken (Screenshot 2024-03-12 at 10.14.07.png). A migration script moved 1,730 referenced images into their page bundles and rewrote the Markdown references; the build's image pipeline then processed them from there, as in Optimizing WebP Images in Hugo Without Plugins.

Step 2: Enforce Size Limits Before Commit

The generator produces optimized variants, so source images only need to be good enough to generate from. Limits of 500 KB for screenshots and 200 KB for diagrams were set, with a pre-commit hook that compresses automatically and a CI check that fails otherwise:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: optimize-images
        name: optimize images
        entry: bash -c 'for f in "$@"; do oxipng -o 4 --strip safe "$f"; done' --
        language: system
        files: \.png$
      - id: image-size-limit
        name: image size limit
        entry: python3 scripts/check_image_size.py --max-kb 500
        language: system
        files: \.(png|jpe?g|webp|gif)$

oxipng recompresses PNGs losslessly, which alone cut the median screenshot from 310 KB to 120 KB. Screenshots taken on high-density displays are also downscaled to a maximum of 2,000 pixels wide by the check script, since the site never displays them larger. The same check runs in CI for contributors who bypass hooks or use the web editor.

Step 3: Decide on Git LFS

With current images at 540 MB and screenshots replaced at every major release, the team moved PNG and JPEG files to Git LFS. Clones then download only the image versions needed for the checked-out commit:

git lfs install
git lfs track "content/**/*.png" "content/**/*.jpg"
git add .gitattributes
git lfs migrate import --include="content/**/*.png,content/**/*.jpg" --everything

git lfs migrate import --everything rewrites history so past image versions move to LFS too, which is what shrinks the repository — and requires every contributor to re-clone, so it was scheduled with notice. CI checkouts use actions/checkout with lfs: true and cache the LFS objects keyed on .lfs-assets-id (a hash of git lfs ls-files -l), so unchanged images are not downloaded on every run.

The alternative for sites with little image churn is plain Git with the size limits above, which avoids LFS setup for every contributor. A third option, external storage (an S3 bucket or an image CDN referenced by URL), suits product screenshots managed by a separate team, at the cost of losing review of image changes in pull requests.

Step 4: Find Unused Images and Missing Alt Text

Two checks run in CI after the build. The unused-image check lists every image file in the content tree and every image referenced in the built HTML, and fails on files referenced by nothing — which, after co-location, are almost always leftovers from an edited page. It found 680 unused images on its first run.

The alt-text check parses the built HTML and fails on content images with no alt attribute, and warns on suspicious alt text: file names (alt="sso-settings.png"), placeholders (alt="image", alt="screenshot") and text longer than 250 characters. It sits alongside the accessibility checks in Accessibility Testing with axe and pa11y in CI. Decorative images use alt="" explicitly, which the check accepts.

Step 5: Automate Screenshots

Hand-taken screenshots vary in window size, zoom level, theme and data, and every UI change makes some of them wrong. The team moved the 400 most-used product screenshots to a Playwright script that logs into a seeded demo environment, navigates to each view and captures it at a fixed viewport, in both light and dark themes:

// screenshots/capture.spec.ts
const shots = [
  { name: 'sso-settings', path: '/settings/sso', selector: '[data-test=sso-panel]' },
  { name: 'install-wizard-step-1', path: '/setup?step=1', selector: 'main' }
];
for (const theme of ['light', 'dark'] as const) {
  for (const s of shots) {
    test(`${s.name} ${theme}`, async ({ page }) => {
      await page.emulateMedia({ colorScheme: theme });
      await page.goto(DEMO + s.path);
      await page.locator(s.selector).screenshot({ path: `out/${s.name}-${theme}.png`, animations: 'disabled' });
    });
  }
}

A scheduled workflow runs the script after each product release and opens a pull request with the changed images, which writers review visually in the diff. Regenerating all 400 screenshots in two themes took 6 minutes, down from about three days of manual work per redesign.

Measured Impact

Pitfalls & Rollback

• Migrating history to LFS without notice. Everyone must re-clone; schedule it.
• LFS bandwidth quotas. CI that downloads all LFS objects on every run can exhaust quotas; cache them.
• Global image folders. Nobody can tell what is safe to delete; co-locate.
• Alt text copied from file names. Check for it; it is worse than useless for screen readers.
• Rollback: git lfs migrate export moves files back into plain Git; size checks and co-location can be reverted independently.

Conclusion

Images are where docs-as-code repositories get heavy and messy. Keep images next to the pages that use them, enforce size limits before commit, move frequently replaced binaries to Git LFS, check for unused images and weak alt text in CI, and generate product screenshots with a script. On this repository that took clones from 94 seconds to 7, removed 680 orphaned files, and turned screenshot refreshes from a multi-day chore into a reviewed pull request.

FAQ

Should documentation images live in the Git repository?

Usually yes, for small and medium sites, because images then version and review together with the text that references them. Very large or frequently replaced binaries, such as high-resolution screenshots updated every release, are better in Git LFS or external storage to keep clones fast.

What should the size limit for committed images be?

Set a limit for source files, such as 500 KB for screenshots and 200 KB for diagrams, and let the build generate optimized variants. Enforce it with a pre-commit hook and a CI check, so oversized files are caught before they enter history, where they stay forever.

Is Git LFS worth the complexity?

For repositories with many large binaries that change often, yes; clones and CI checkouts become much faster. It adds setup for every contributor and CI job, and hosting providers meter LFS bandwidth, so for small image sets plain Git with size limits is simpler.

How do I keep screenshots up to date?

Generate them from the product with a script, for example with Playwright against a demo environment, and rerun the script on each release. Automated screenshots are consistent in size and theme and can be regenerated in minutes when the UI changes.

Related

• Parent: Content Workflows for Documentation Teams — the whole docs-as-code workflow.
• Docs-as-Code Review Workflow for Writers — reviewing image changes.
• Content Linting with markdownlint — the text-side checks.
• Caching Hugo Builds in GitHub Actions — faster checkouts and builds.
• Visual Regression Testing on Preview Deploys — the same Playwright tooling for layout checks.