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())
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
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)
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.
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
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)