The Ops Community ⚙️

Cover image for Catch Broken Markdown Images in CI Before Publishing
fluxpro net
fluxpro net

Posted on

Catch Broken Markdown Images in CI Before Publishing

A documentation change can pass a link check and still ship a broken image. An expired sharing link, for example, may return HTTP 200 and serve a sign-in page instead of the file. A second failure is even easier to miss during review. The screenshot path exists on the author's laptop, but the file was never committed.

Run a small check on the Markdown before merging. Resolve relative targets from the document's directory. For a trusted remote URL, check the status, media type and the first bytes of the response. The failure message should point to the document and the block where the reference appears.

Add the checker

Save this as check_markdown_images.py at the repository root. It reads CommonMark image references, including reference-style images. Fenced code, raw HTML images and site-specific asset rewriting are outside its scope.

"""Check CommonMark image targets, with network checks disabled by default."""
import argparse
from http.client import HTTPException
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import unquote, urldefrag, urlsplit
from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener

from markdown_it import MarkdownIt

MAGIC = {
    "image/png": (b"\x89PNG\r\n\x1a\n",),
    "image/jpeg": (b"\xff\xd8\xff",),
    "image/gif": (b"GIF87a", b"GIF89a"),
}


class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None


def image_targets(markdown):
    parser = MarkdownIt("commonmark", {"html": False})
    for block in parser.parse(markdown):
        if block.type == "inline":
            for child in block.children or []:
                if child.type == "image":
                    yield block.map[0] + 1, child.attrGet("src")


def check_target(src, document, root, allowed, allow_loopback):
    address = urlsplit(src)
    if address.scheme or address.netloc:
        url, _ = urldefrag(src)
        if url not in allowed:
            return "remote target has no explicit allowlist entry"
        loopback = allow_loopback and address.scheme == "http" and address.hostname == "127.0.0.1"
        if (address.scheme != "https" and not loopback) or not address.hostname:
            return "expected HTTPS or explicitly enabled loopback test URL"
        if address.username is not None or address.password is not None:
            return "URL credentials are not permitted"
        opener = build_opener(ProxyHandler({}), NoRedirect())
        try:
            request = Request(url, headers={"Accept-Encoding": "identity"})
            with opener.open(request, timeout=4) as response:
                if response.status != 200:
                    return f"expected HTTP 200, got {response.status}"
                mime = response.headers.get_content_type()
                prefix = response.read(12)
                if not prefix.startswith(MAGIC.get(mime, ())):
                    return f"HTTP 200, {mime}, expected PNG, JPEG or GIF bytes"
        except HTTPError as error:
            return f"HTTP {error.code} (redirects disabled)"
        except (URLError, OSError, HTTPException, ValueError) as error:
            return f"GET failed: {error}"
    else:
        local = Path(unquote(address.path))
        if not address.path or local.is_absolute():
            return "expected an image path relative to this Markdown file"
        path = (document.parent / local).resolve()
        if not path.is_relative_to(root) or not path.is_file():
            return "image file is missing or outside the repository"
    return None


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path("."))
    parser.add_argument("--allow-url", action="append", default=[])
    parser.add_argument("--allow-loopback", action="store_true", help="for local fixtures only")
    parser.add_argument("documents", type=Path, nargs="+")
    args = parser.parse_args()
    root = args.root.resolve()
    allowed = set(args.allow_url)
    failures = 0
    count = 0
    for document in args.documents:
        document = document.resolve()
        if not document.is_relative_to(root):
            parser.error("all documents must be inside the repository root")
        for line, src in image_targets(document.read_text(encoding="utf-8")):
            count += 1
            try:
                problem = check_target(src, document, root, allowed, args.allow_loopback)
            except (ValueError, OSError, RuntimeError) as error:
                problem = f"invalid image target: {error}"
            if problem:
                failures += 1
                print(f"{document.relative_to(root)}:{line}: {problem}")
    print(f"Checked {count} Markdown images, {failures} failures.")
    return int(failures > 0)


if __name__ == "__main__":
    raise SystemExit(main())
Enter fullscreen mode Exit fullscreen mode

Install the same parser version used in the workflow. List the Markdown files your team ships.

python -m pip install markdown-it-py==4.0.0
python check_markdown_images.py README.md
Enter fullscreen mode Exit fullscreen mode

The default command checks local paths and reports any remote targets for review before sending a request. For an anonymous HTTPS image you own or trust, pass its exact URL using --allow-url. Supply one flag per URL and omit URL fragments from the allowlist. Put these URLs in reviewed workflow configuration, separate from contributor-controlled Markdown. Each GET reads up to 12 bytes with a four-second socket timeout. Redirects and environment proxies are disabled. Keep the job timeout too, since the socket timeout bounds individual operations.

The local check confirms the file exists within the repository. The remote check recognizes PNG, JPEG and GIF signatures and compares them against the response media type. A matching signature can catch a wrong payload early. A full image decode, browser policy, permissions and the final layout still need a rendered preview.

Reproduce the failure locally

Save this fixture runner next to the checker. It starts an HTTP server on the loopback interface, exercises a reference-style image and a valid remote response, then checks a missing file, a login page, a redirect, an unapproved URL and HTML mislabeled as PNG.

"""Run a deterministic local HTTP and filesystem fixture against the checker."""
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
import struct
import subprocess
import sys
from tempfile import TemporaryDirectory
from threading import Thread
import zlib


def png_chunk(kind, data):
    payload = kind + data
    return struct.pack(">I", len(data)) + payload + struct.pack(">I", zlib.crc32(payload))


# One black RGB pixel, preceded by the PNG scanline filter byte (0).
PNG = (
    b"\x89PNG\r\n\x1a\n"
    + png_chunk(b"IHDR", struct.pack(">IIBBBBB", 1, 1, 8, 2, 0, 0, 0))
    + png_chunk(b"IDAT", zlib.compress(b"\x00\x00\x00\x00"))
    + png_chunk(b"IEND", b"")
)
HTML = b"<html>Sign in</html>"
CHECKER = Path(__file__).with_name("check_markdown_images.py").resolve()


class Fixture(BaseHTTPRequestHandler):
    requests = []

    def do_GET(self):
        self.requests.append(self.path)
        if self.path == "/redirect":
            self.send_response(302)
            self.send_header("Location", "/must-not-be-called")
            self.end_headers()
            return
        mime, body = {
            "/good.png": ("image/png", PNG),
            "/login": ("text/html", HTML),
            "/wrong-magic.png": ("image/png", HTML),
        }.get(self.path, ("text/plain", b"unexpected request"))
        self.send_response(200)
        self.send_header("Content-Type", mime)
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *args):
        pass


def run(root, filename, markdown, *args):
    (root / filename).write_text(markdown, encoding="utf-8")
    result = subprocess.run(
        [sys.executable, str(CHECKER), "--root", str(root), *args, str(root / filename)],
        capture_output=True, text=True, timeout=15, check=False,
    )
    print(f"{filename} -> exit {result.returncode}\n{result.stdout}", end="")
    assert not result.stderr, result.stderr
    return result.returncode, result.stdout


with TemporaryDirectory() as folder, ThreadingHTTPServer(("127.0.0.1", 0), Fixture) as server:
    root = Path(folder)
    (root / "good.png").write_bytes(PNG)
    thread = Thread(target=server.serve_forever, daemon=True)
    thread.start()
    base = f"http://127.0.0.1:{server.server_port}"
    try:
        rc, log = run(
            root, "good.md",
            f"!\x5bLocal][pic]\n\n\x5bpic]: good.png\n\n!\x5bRemote]({base}/good.png)\n"
            '`!\x5bCode](missing.png)`\n',
            "--allow-loopback", "--allow-url", f"{base}/good.png",
        )
        assert rc == 0 and "Checked 2 Markdown images, 0 failures." in log
        rc, log = run(
            root, "broken.md",
            f"!\x5bMissing](missing.png)\n\n!\x5bLogin]({base}/login)\n\n"
            f"!\x5bRedirect]({base}/redirect)\n\n!\x5bBlocked]({base}/unlisted)\n\n"
            f"!\x5bSpoofed MIME]({base}/wrong-magic.png)\n",
            "--allow-loopback", "--allow-url", f"{base}/login",
            "--allow-url", f"{base}/redirect", "--allow-url", f"{base}/wrong-magic.png",
        )
        assert rc == 1 and "Checked 5 Markdown images, 5 failures." in log
        for line, clue in [
            (1, "missing"), (3, "HTTP 200, text/html"), (5, "HTTP 302"),
            (7, "no explicit allowlist"), (9, "HTTP 200, image/png"),
        ]:
            assert any(f"broken.md:{line}:" in row and clue in row for row in log.splitlines()), log
        assert Fixture.requests == ["/good.png", "/login", "/redirect", "/wrong-magic.png"]
        print("Fixture assertions passed. No redirect or non-allowlisted request was sent.")
    finally:
        server.shutdown()
        thread.join(timeout=5)
Enter fullscreen mode Exit fullscreen mode

Run it with python test_check_markdown_images.py. Here is the observed output from Python 3.12 and markdown-it-py 4.0.0. The intentionally broken document returns exit 1 inside the fixture. The fixture runner itself succeeds after checking both cases and the server's request log.

good.md -> exit 0
Checked 2 Markdown images, 0 failures.
broken.md -> exit 1
broken.md:1: image file is missing or outside the repository
broken.md:3: HTTP 200, text/html, expected PNG, JPEG or GIF bytes
broken.md:5: HTTP 302 (redirects disabled)
broken.md:7: remote target has no explicit allowlist entry
broken.md:9: HTTP 200, image/png, expected PNG, JPEG or GIF bytes
Checked 5 Markdown images, 5 failures.
Fixture assertions passed. No redirect or non-allowlisted request was sent.
Enter fullscreen mode Exit fullscreen mode

Wire the local check into GitHub Actions

Save the workflow as .github/workflows/markdown-images.yml. This example runs on a GitHub-hosted runner with read-only repository permissions. The pull request command supplies no remote allowlist. If your docs require remote images, use the approved URL flags in a separate trusted job. Replace README.md with the set of Markdown files you intend to check and make the job a required check if your team wants it to gate merges.

name: Markdown images
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
        with:
          persist-credentials: false
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
        with:
          python-version: "3.12"
      - run: python -m pip install markdown-it-py==4.0.0
      - run: python check_markdown_images.py README.md
Enter fullscreen mode Exit fullscreen mode

If a reference fails with text/html, open the intended image URL in a signed-out browser and replace the share page with the direct file URL or a committed image. If the checker flags a missing local file, compare the spelling and case against the repository tree. Preview the resulting page once before publishing to verify the image actually appears in the intended place.

References: markdown-it-py usage, Python request handling, and GitHub Actions workflow syntax.

Top comments (0)