LITERARY MACHINES

mkiiif, yet another static IIIF generator

2026-03-19T00:00:00+00:00

I revisited an old Go package</a> I've been using over the past few years to build IIIF manifests — nothing fancy, just some glue around structs and JSON. From that I built a new CLI, mkiiif</code>, to generate IIIF manifests from static images (tiled or not). There are plenty of similar tools out there (iiif-tiler</a>, tile-iiif</a>, biiif</a>, ...) but none quite matched the CLI ergonomics I needed for my daily workflow.</p>

I moved the library to this new repository atomotic/iiif</a>. The tool mkiiif</a> can be installed downloading a binary release</a> or with Go:</p>

go install github.com/docuverse/iiif/cmd/mkiiif@latest</span></span></code></pre>
mkiiif</code> can generate an IIIF manifest from a source directory containing images</strong>, or from a PDF file</strong> that gets exploded and converted to images via mupdf</code>. Output images can be either untiled or static tiles generated with vips</code>. Both approaches produce a IIIF Level 0</a> compliant layout, static files that can be served from any HTTP server, with no image server required. Untiled is less efficient for large images but perfectly fine for printed books, papers, and similar material.</p>
mupdf</a> and vips</a> are external dependencies, that need to be installed separately. They are invoked via subprocess; I chose not to add Go library wrappers around them to keep the tool simple. WASM ports of both may become viable in the future.</p>
The CLI usage:</p>
Usage:</span> mkiiif</span> -id</span> <</span>i</span>d</span>></span> -base</span> <</span>ur</span>l</span>></span> -title</span> <</span>titl</span>e</span>></span> -source</span> <</span>dir</span>|</span>pdf</span>></span> -destination</span> <</span>di</span>r</span>></span> [-tiles]</span></span>
  -base</span> string</span></span>
        Base</span> URL where the manifest will be served</span> (e.g.</span> https://example.org/iiif</span>)</span></span>
  -destination</span> string</span></span>
        Output</span> directory</span>;</span> a</span> subdirectory named</span> <</span>i</span>d</span>></span> will be created inside it, containing the images and manifest.json</span></span>
  -id</span> string</span></span>
        Unique</span> identifier for the manifest</span> (e.g.</span> book1</span>)</span></span>
  -resolution</span> int</span></span>
        Resolution</span> (DPI) used when converting PDF pages to images via mutool (</span>default</span> 150</span>)</span></span>
  -source</span> string</span></span>
        Path</span> to a directory of images or a PDF file to convert</span></span>
  -tiles</span></span>
        Generate</span> IIIF image tiles for each image using vips dzsave</span> (requires</span> vips</span>)</span></span>
  -title</span> string</span></span>
        Human-readable</span> title of the manifest</span></span></code></pre>
Example:</p>
~</span> mkiiif -base https://digital.library.org -destination ./public -id iiif01 -source </span>~</span>/book.pdf -title </span>"iiif 01"</span></span></code></pre>
Or with tiling:</p>
~</span> mkiiif -base https://digital.library.org -destination ./public -id iiif01 -source </span>~</span>/book.pdf -title </span>"iiif 01"</span> -tiles</span></span></code></pre>
Both commands produce the following structure inside ./public</code>:</p>
└── iiif01</span></span>
    ├── index.html</span></span>
    ├── manifest.json</span></span>
    ├── page-001.png</span></span>
    ├── page-002.png</span></span>
    ├── page-....png</span></span>
    └── page-....png</span></span></code></pre>└── iiif01</span></span>
│   ├── index.html</span></span>
│   ├── manifest.json</span></span>
│   ├── page-001</span></span>
│   │   ├── 0,0,1024,1024</span></span>
│   │   │   └── 512,512</span></span>
│   │   │       └── 0</span></span>
│   │   │           └── default.jpg</span></span>
...</span></span>
│       ├── full</span></span>
│       │   ├── 362,501</span></span>
│       │   │   └── 0</span></span>
│       │   │       └── default.jpg</span></span>
│       │   └── max</span></span>
│       │       └── 0</span></span>
│       │           └── default.jpg</span></span>
│       └── info.json</span></span>
...</span></span></code></pre>
The directory can then be served from https://digital.library.org</code>.</p>
I've adopted this URL scheme:</p>
https://{</span>base</span>}/{</span>id</span>}</span></span>
    /manifest.json — the IIIF manifest</span></span>
    /index.html    — a simple viewer</span></span></code></pre>
So in the example above, https://digital.library.org/iiif01</code> opens a full viewer to browse the object. The viewer used is Triiiceratops</a></strong> — the newest viewer in the IIIF ecosystem. Built on Svelte and OpenSeadragon, is still young, but very usable, lightweight, and easy to embed and customize. It is my favourite viewer.</p>
mkiiif</code> doesn't handle metadata for now (and probably won't) — the manifest can be easily patched to insert descriptive metadata in a later step, after image preparation, pulling from any existing datasource or metadata catalog.</p>
Here is a full working example: https://docuver.se/iiif/p3tgsk8jqt/</a></p>
A few open questions I haven't fully resolved:</p>

The main drawback of generating IIIF this way is that you end up managing a large number of files on the filesystem, and handling millions of small image tiles can be slow (and costly). This is where IIIF intersects — and overlaps — with similar practices in digital preservation, such as  BagIt, OCFL, and WARC/WACZ. So far there's no specification or viewer implementation that handles IIIF containers (e.g. a zip file bundling images, tiles, and the manifest). Discussions on this have been ongoing</a> in the past; I've recently been looking at analogous approaches like GeoTIFF</a> and SZI</a>.</li>
A static IIIF bundle generated with this CLI still needs to be served from an HTTP server, with the base URL defined at derivation time. Could such a bundle be opened from localhost and viewed directly in the browser? Service Workers might help here (even if HTTP is still needed), but it's a rabbit hole I haven't explored yet.</li>
</ul>
The CLI is pretty bare-bones — feel free to suggest improvements or report bugs. I've been using it over the past weeks as part of a personal project: an amateur digital library built around a DIY book scanner I assembled at home, to preserve magazines, zines, and similar material (content NSFW and out of scope to link here).</p>



Build a static search for an Internet Archive Collection with Pagefind
2026-03-07T00:00:00+00:00
Pagefind</a> caught my attention about a year ago, and since then I've adopted it in several hobby projects (nothing work-related): some blogs built with static generators like Hugo or Zola, some old HTML content distributed on CD-ROM, and some mailing list archives where I converted mbox files to HTML and then indexed them.</p>
The tool is great, better for my needs than other JavaScript search libraries (though it's not really fair to compare them, since they're quite different). Pagefind is a search tool that runs entirely in the browser with zero server-side dependencies. It indexes your content into a compact binary index, using WASM to run search in the browser.</p>
It can't completely replace server-side search technologies like Solr or Elasticsearch, mainly because the index can't be updated incrementally. But for many small to medium digital libraries or collections that are rarely updated once completed, it's an extremely good tool: very fast, easy to integrate into web pages, and requires almost no maintenance.</p>
Until now I was convinced that the only way to build an index was by reading content from existing HTML files. That changed when I listened to this Python in Digital Humanities</a> podcast, where David Flood</a> mentioned:</p>

Critically, PageFind has a Python API that lets you build indexes programmatically from database dumps rather than only from HTML files.</p>
</blockquote>
I'd completely missed that Pagefind has a Python API</a> (and a Node one too), which makes it easy to build an index from any data source.</p>

Here's a basic example: building a search index for an Internet Archive collection.</p>
I'm using the Pagefind pre-release</a> here, which introduces a new UI with web components</a>.</p>
Init</strong></p>
uv init .</span></span>
uv add internetarchive</span></span>
uv add --prerelease=allow 'pagefind[bin]'</span></span></code></pre>
Directory to save the index and serve the UI</strong></p>
mkdir ./web</span></span></code></pre>
Python code:</strong> create an index from metadata of this collection</a> (that is actually a collection of subcollections in Internet Archive, Italian content, related to radical movements)</p>
import</span> asyncio</span></span>
import</span> logging</span></span>
import</span> os</span></span>
</span>
import</span> internetarchive</span></span>
from</span> pagefind.index</span> import</span> PagefindIndex, IndexConfig</span></span>
</span>
logging.basicConfig(</span>level</span>=</span>os.environ.get(</span>"LOG_LEVEL"</span>,</span> "DEBUG"</span>))</span></span>
log</span> =</span> logging.getLogger(__name__)</span></span>
</span>
</span>
async def</span> main</span>():</span></span>
    config</span> =</span> IndexConfig(</span>output_path</span>=</span>"./web/pagefind"</span>)</span></span>
</span>
    async with</span> PagefindIndex(</span>config</span>=</span>config)</span> as</span> index:</span></span>
        log.info(</span>"Searching collection:radical-archives ..."</span>)</span></span>
        results</span> =</span> internetarchive.search_items(</span></span>
            "collection:radical-archives"</span>,</span></span>
            fields</span>=</span>[</span>"identifier"</span>,</span> "title"</span>,</span> "description"</span>],</span></span>
        )</span></span>
</span>
        count</span> =</span> 0</span></span>
        for</span> item</span> in</span> results:</span></span>
            identifier</span> =</span> item.get(</span>"identifier"</span>,</span> ""</span>)</span></span>
            title</span> =</span> item.get(</span>"title"</span>, identifier)</span></span>
            description</span> =</span> item.get(</span>"description"</span>,</span> ""</span>)</span></span>
            url</span> =</span> f</span>"https://archive.org/details/</span>{</span>identifier</span>}</span>"</span></span>
            thumbnail</span> =</span> f</span>"https://archive.org/services/img/</span>{</span>identifier</span>}</span>"</span></span>
</span>
            if</span> isinstance</span>(description,</span> list</span>):</span></span>
                description</span> =</span> " "</span>.join(description)</span></span>
</span>
            await</span> index.add_custom_record(</span></span>
                url</span>=</span>url,</span></span>
                content</span>=</span>description</span> or</span> title,</span></span>
                language</span>=</span>"en"</span>,</span></span>
                meta</span>=</span>{</span></span>
                    "title"</span>: title,</span></span>
                    "description"</span>: description,</span></span>
                    "image"</span>: thumbnail,</span></span>
                },</span></span>
            )</span></span>
            count</span> +=</span> 1</span></span>
            log.debug(</span>"indexed </span>%s</span>: </span>%s</span>"</span>, identifier, title)</span></span>
</span>
        log.info(</span>"Indexed </span>%d</span> items. Writing index ..."</span>, count)</span></span>
</span>
    log.info(</span>"Done. Index written to ./web/pagefind"</span>)</span></span>
</span>
</span>
if</span> __name__</span> ==</span> "__main__"</span>:</span></span>
    asyncio.run(main())</span></span></code></pre>
HTML UI in ./web/index.html</code></strong></p>
<!</span>DOCTYPE</span> html</span>></span></span>
<</span>html</span> lang</span>=</span>"en"</span>></span></span>
	<</span>head</span>></span></span>
		<</span>meta</span> charset</span>=</span>"UTF-8"</span>></span></span>
		<</span>meta</span> name</span>=</span>"viewport"</span> content</span>=</span>"width=device-width, initial-scale=1.0"</span>></span></span>
		<</span>title</span>>pagefind-ia</</span>title</span>></span></span>
		<</span>link</span> href</span>=</span>"/pagefind/pagefind-component-ui.css"</span> rel</span>=</span>"stylesheet"</span>></span></span>
		<</span>script</span> src</span>=</span>"/pagefind/pagefind-component-ui.js"</span> type</span>=</span>"module"</span>></</span>script</span>></span></span>
	</</span>head</span>></span></span>
	<</span>body</span>></span></span>
		<</span>pagefind-modal-trigger</span>></</span>pagefind-modal-trigger</span>></span></span>
		<</span>pagefind-modal</span>></span></span>
			<</span>pagefind-modal-header</span>></span></span>
				<</span>pagefind-input</span>></</span>pagefind-input</span>></span></span>
			</</span>pagefind-modal-header</span>></span></span>
			<</span>pagefind-modal-body</span>></span></span>
				<</span>pagefind-summary</span>></</span>pagefind-summary</span>></span></span>
				<</span>pagefind-results</span> show-images</span>></</span>pagefind-results</span>></span></span>
			</</span>pagefind-modal-body</span>></span></span>
			<</span>pagefind-modal-footer</span>></span></span>
				<</span>pagefind-keyboard-hints</span>></</span>pagefind-keyboard-hints</span>></span></span>
			</</span>pagefind-modal-footer</span>></span></span>
		</</span>pagefind-modal</span>></span></span>
	</</span>body</span>></span></span>
</</span>html</span>></span></span></code></pre>
Result</strong>: easy to embed it anywhere!</p>