A production documentation site, rebuilt as two Nift projects. Preserved Markdown for humans and agents. Maintained HTML for agents under human direction.
Docker Docs uses Hugo. We pinned its source and reconstructed the publication, routes, metadata, search, downloads, redirects and browser interactions. This is a real migration experiment with architecture and maintenance tradeoffs.
Independent Nift experiment. Not endorsed by Docker. Nift itself was not modified.
Performance claims follow the acceptance gates. The full publication is the oracle, not a handful of similar-looking pages.
8,622publication files per project
3,901HTML documents
2,170content pages + downloads
2,142searchable routes
31,268distinct search words
192browser states per project
SHA-256 / PASSED
Every optimized publication file has the same SHA-256 as the accepted initial migration: all 8,622 files in each project. That proves optimization preserved the accepted migration; it does not claim every output byte equals Hugo.
Publication + browser behavior
All HTML route contracts and content-page comparisons pass. Search words, counts, metadata, filters, anchors and locations match. All 192 required screenshots per project are pixel-identical to the pinned reference, with zero tested DOM or behavior differences.
Checks cover responsive navigation, theme changes, search, tabs, accordions, copy controls, Gordon UI and API interactions.
Changes have to publish correctly
Route addition, rename and deletion pass. Previous outputs are retired; metadata, canonical links, navigation, TOC, downloads, sitemap and search remain coherent. Changed-input builds match forced full output, and all ten optimized fresh checkouts reproduce the accepted publication.
Nift 4.7.2 remains unchanged throughout.
Accepted differences and validation boundaries
The migration retains accepted HTML-derived Markdown formatting, semantic XML whitespace equivalence and RSS generator attribution. Human Pagefind fragments differ in 144 sentence-boundary punctuation cases; the indexed route/word/metadata/anchor contracts match. Agent fragments match exactly.
Inherited upstream issues remain recorded: 576 missing descriptions, 2,154 duplicate-ID observations, 80 missing fragments, four missing local targets, 54 empty metadata URLs and 38 absent redirect targets. This pass introduces none.
Browser tests intercept remote requests. They establish tested local UI behavior, not live Docker AI, consent, telemetry or remote Redoc/backend availability. No prompts, feedback or telemetry were sent.
No routine Markdown renderer, generated-reference transformation or HTML minification stage. These are the maintained-HTML architecture’s disclosed boundaries.
A Docker compatibility layer, bounded by evidence.
The human renderer implements the pinned corpus’s required shortcode/include behavior and seven render-hook categories, backed by real Docker fixtures. It does not attempt to recreate Hugo generally. Literal template/Nift-like syntax survives raw composition; mount and published-path normalization are explicit.
These timings are standalone compatibility rendering plus Nift orchestration/composition, not native @markup performance. The two pipelines are not equivalent authoring-model benchmarks.
03 / benchmarks
Count the whole build.
Five serialized samples per workflow. Medians and complete ranges, with publication and Pagefind included.
Warm full pipeline
Forced full build · elapsed median
017.535 s
Hugo29.12 s
5 runs · 27.74–30.55 s
Nift docker21.83 s
5 runs · 21.61–22.47 s
Nift docker-agent14.65 s
5 runs · 13.56–14.91 s
Fresh committed checkout
Empty application state/output · elapsed median
017.535 s
Hugo34.46 s
5 runs · 31.28–38.19 s
Nift docker23.75 s
5 runs · 23.46–23.99 s
Nift docker-agent15.20 s
5 runs · 14.87–15.67 s
Warm process/phase RSS
Median of each run’s largest measured process/phase maximum
08001600 MiB
Hugo1532.8 MiB
5 runs · 1465.7–1574.3 MiB
Nift docker441.6 MiB
5 runs · 441.3–442.1 MiB
Nift docker-agent391.7 MiB
5 runs · 390.7–393.3 MiB
All bars use the labelled zero-origin linear scales. Ranges are min–max over five samples. RSS is an individual process/phase high-water mark, not aggregate simultaneous pipeline memory; parallel analysis workers require a different accounting boundary.
docker / warm full
61.52s initial→21.83s optimized
docker-agent / warm full
30.27s initial→14.65s optimized
First we finished the faithful migration. Then we profiled and optimized it while preserving every accepted publication hash. The initial evidence is retained independently. Fresh medians also fell: 66.66 → 23.75 s for docker and 30.03 → 15.20 s for docker-agent.
This is a local production-workflow comparison. The migrations retain compiled upstream frontend assets; the native Hugo pipeline includes its generation/minification and asset work, flatten processing, API verification and Pagefind. Tool installation is outside timing. Read the measurement boundaries ↗
04 / profiling
The expensive work surrounded the Markdown.
Raw Markdown parse/render was well under a second in the original human pipeline. Shared shell, repeated HTML analysis and minification explained much more of the total.
REUSE
Prepare shared structure once.
Navigation values/adjacency and invariant branches are reused. Templates are read once; generated route HTML is no longer retained in a large Python cache. Human shell preparation fell from 16.19 to 2.68 s; agent preparation from 15.62 to 3.53 s.
ANALYZE
One body parse, two outputs.
A shared four-worker analysis supplies heading bindings and Markdown downloads. Forced full builds still analyze/export all 2,170 pages. Export writes are now small because parsing/conversion is measured in joint analysis, not omitted.
BATCH
Keep minification. Remove repetition.
Eight human minifier workers and a bounded, exact-input SVG cache preserve output bytes. Minification fell from 19.78 to 1.81 s. YAML reuse, safe C-backed loading and Chroma lexer reuse also reduce compatibility overhead.
Optimized warm full · five-run component medians
Outer stage
docker
docker-agent
Docker compatibility
6.350 s
—
Shared shell
2.683 s
—
Composition preparation
—
3.535 s
Joint body analysis
2.420 s
2.527 s
Nift composition
2.852 s
3.229 s
HTML minification
1.806 s
—
Download write
0.072 s
0.070 s
Ancillary publication
0.264 s
0.154 s
Assets
0.036 s
0.039 s
Pagefind preparation + index
3.831 s
4.036 s
Nested inside the human compatibility stage: Markdown parse 0.381 s, Markdown render 0.156 s, hooks 0.330 s, Chroma 1.703 s. Typed CLI/API generation and shortcode expansion are included in that outer stage. Hook timing includes lexer discovery; Chroma measures tokenization/formatting.
Do not add nested counters twice. Parallel-worker wall sums are not elapsed stage time; component medians need not sum to the whole-pipeline median. Joint analysis includes HTML parsing and download conversion. Process startup and other orchestration also contribute.
SEARCH / INCLUDED
A correct index has a real fixed cost.
Fresh Pagefind remains in every publication. Preparation and indexing are recorded separately; indexing costs roughly four seconds in the optimized runs. A narrower update needs a proven projection of every search-visible field. We retained correct full indexing instead of inventing incremental Pagefind behavior or dropping search from edit timings.
Memory for changed-input production publications, separate from full-build memory and elapsed time. Linear bars start at zero; exact values are shown in MiB.
GNU time maximum individual process/phase RSS; not aggregate simultaneous pipeline RSS
0430 MiB
1-page
Nift docker390.8 MiB
Nift docker-agent393.0 MiB
10-pages
Nift docker391.7 MiB
Nift docker-agent391.6 MiB
100-pages
Nift docker391.9 MiB
Nift docker-agent392.3 MiB
layout
Nift docker425.4 MiB
Nift docker-agent392.3 MiB
navigation
Nift docker392.1 MiB
Nift docker-agent391.9 MiB
metadata
Nift docker392.2 MiB
Nift docker-agent391.6 MiB
Five original samples per case: median [min–max], same Nift runs as accepted changed-input timings. Hugo is the retained initial production cohort, separate from optimized Nift; not dev/HMR or paired cohort evidence. Full case tables and evidence below retain the other scopes and workloads.
Full builds regenerate the publication. Changed-input builds reuse unaffected work, then validate the result against a forced full rebuild.
Publish-ready incremental builds · five edits per case · search included
Change
docker
docker-agent
1 body
9.23 s5.13 project + 4.05 searchRange 9.00–9.31 s
6.43 s2.59 project + 3.92 searchRange 6.34–6.66 s
10 bodies
9.64 s5.37 project + 4.21 searchRange 9.14–9.98 s
7.10 s2.82 project + 4.28 searchRange 6.64–10.78 s
100 bodies
11.26 s6.96 project + 4.31 searchRange 10.56–11.38 s
7.40 s3.29 project + 3.87 searchRange 6.99–7.75 s
Shared footer
16.27 s12.49 project + 3.95 searchRange 15.59–17.92 s
12.18 s8.33 project + 3.85 searchRange 12.01–12.78 s
Navigation label
13.95 s9.62 project + 4.25 searchRange 12.80–16.45 s
10.55 s6.60 project + 3.99 searchRange 10.32–11.22 s
Title metadata
9.20 s4.80 project + 4.28 searchRange 8.58–10.01 s
6.68 s2.57 project + 3.98 searchRange 6.47–6.79 s
Project work is elapsed publication time minus measured search time. Separately calculated medians may not add exactly. Every case’s first edit equals forced full output; all 60 measured edits restore every original publication hash.
Precise invalidation pays off.
Human body edits compile exactly 1, 10 or 100 changed pages. Footer, navigation and title edits compile zero bodies. A title change no longer rerenders all 2,170 pages: its whole median fell from 71.30 to 9.20 s. Footer fell from 47.44 to 16.27 s; navigation from 54.63 to 13.95 s.
Small edits are still search-limited.
One- and ten-page medians are slightly higher than the original migration in both projects. Full/shared-input gains do not mean every edit improved. Fresh search is retained, and these later active-desktop samples show higher indexing costs. Initial values and all ranges remain in the evidence.
The retained Hugo changed-input runs are full production CLI publications. They are not Hugo development-server hot reload. No claim is made that Hugo lacks development caching, or that these Nift edits beat its unmeasured server workflow.
Iteration memory / peak RSS
Incremental memory matters alongside elapsed time: a smaller affected build can leave more headroom for concurrent builds, CI jobs and agents on constrained machines. Shared changes and retained worker pools can still use substantial memory; an incremental build is not guaranteed to have a lower peak than a full build. Actual concurrency and total workflow productivity were not benchmarked.
GNU time maximum individual process/phase RSS; not aggregate simultaneous pipeline RSS. Five original samples per case: median [min–max], same Nift runs as accepted changed-input timings. Hugo is the retained initial production cohort, separate from optimized Nift; not dev/HMR or paired cohort evidence.
Build time matters, but the maintained representation determines editing, review and ownership.
323shared chrome templates
4.55 MBshared chrome source
4.27 MBsame published JS in both
Both use explicit route, navigation and metadata models and preserve Docker’s frontend interactions. The ten published JavaScript files total 4,266,240 bytes in each project; these are uncompressed totals, not per-page downloads. A simpler build does not mean less shipped JavaScript.
docker
Conventional editorial source.
Markdown/frontmatter remain familiar; readable diffs and structured CLI/API sources retain their authority. The source tree preserves useful Docker organization.
The responsibility
A Docker-specific compatibility layer, more transformation work and runtime dependencies. New corpus behavior requires a real fixture and a bounded port. Explicit family/route/metadata bindings and retained frontend assets must stay coherent.
docker-agent
Rendered HTML as source.
3,902 maintained HTML page files, including setup/auxiliary files, for 3,901 published documents. Agents edit rendered bodies directly; normal builds omit Markdown and source-derived reference generation.
The responsibility
Keep associated metadata, navigation and export state coherent. Specialized references are maintained rendered output. There is no conventional Markdown authoring workflow; human direction and review still matter.
Human routine tooling adds safe PyYAML, standalone Goldmark/Chroma/GoAT and pinned minification libraries. Agent routine builds use Python’s standard library, Nift and Pagefind. Both retain compiled upstream frontend assets; changing the frontend/tooling remains a separate engineering responsibility.
07 / assessment
What would this agent maintain?
An explicit engineering assessment from working on both implementations. These preferences are not measurements of long-term productivity or editing reliability.
01 / AGENTS IMPLEMENT, HUMANS DIRECT
I would choose docker-agent.
For routine agent-led maintenance, removing content and generated-reference transformation makes the operational pipeline easier to reason about. Explicit HTML, shared structures and metadata mappings are workable for agents, and the materially smaller full-build cost makes repeated publication checks cheaper.
I would accept the duty to update related metadata and references coherently. Large source representations are manageable, but they still need review and parity/lifecycle gates.
02 / HUMANS AND AGENTS BOTH EDIT
I would choose docker.
Markdown/frontmatter and structured CLI/API sources make ordinary human contributions more familiar and reviewable. I would keep those authoritative inputs rather than ask people to maintain rendered reference HTML. The optimized whole build is already below this experiment’s measured Hugo production pipeline.
The bounded compatibility code is a real maintenance cost. I would accept it for the demonstrated corpus, while requiring fixtures for new behavior and clear ownership of frontend/tooling changes.
03 / BOTH ALREADY EXIST; NO MIGRATION DECISION
The same source-model preference holds.
If both implementations were already accepted, with equally available required services, I would maintain docker-agent for agent-only implementation under human direction, and docker for mixed human+agent editing. This preference excludes migration effort and incumbency; it follows the ongoing maintenance responsibilities.
We did not measure total agent cost, human editing effort or long-term productivity. Build feedback is only one part of the maintenance loop.
08 / official migration
Worth a serious engineering evaluation.
Would this justify Docker investigating an official Nift migration? My assessment is yes. It does not establish that Docker should definitely migrate.
AGENT JUDGMENT
The benefits are substantial enough to investigate.
The preserved-Markdown implementation improved full publication time and measured process/phase RSS while preserving the accepted corpus and tested browser behavior. Dependency-aware shared-input builds and successful route lifecycle checks make this more than a throughput demonstration.
The next decision belongs to Docker’s engineering workflow: weigh compatibility ownership, new-content discovery/validation, frontend regeneration, CI/deployment integration and moving away from an established Hugo toolchain. The smaller operational architecture of maintained HTML is attractive only if that authoring model fits.
I would propose a scoped engineering evaluation, with real contributor edits, frequent upstream changes and Docker’s actual CI/container deployment and service integrations. Production certification, team ergonomics and ongoing maintenance cost remain to be demonstrated. Performance alone does not establish universal superiority or justify an unqualified platform switch.
09 / methodology
Keep the boundaries attached.
A skeptical engineer should be able to identify the work, the retained state and the limits of each number.
Upstream pin
6cf1b1c167f032e8a6629da211602300b623b20e Docker’s public docs repository
Native reproduction
Production Hugo generation/minification → flatten tests/processing → API verification → Pagefind. Docker was unavailable on the host: this is not an Alpine/BuildKit benchmark.
Samples
Five serialized samples per workflow/case. Medians and min–max ranges. No fastest-run substitution; diagnostic/tuning trials remain separate.
Fresh state
Committed checkouts; empty application caches/output. Prepared binaries and dependencies, clone and validation excluded. OS caches uncontrolled: application-cold, not machine-cold.
Host + concurrency
Intel i7-12700H, 20 logical CPUs, about 61 GiB RAM. An active desktop, not an isolated server. Analysis: four workers; human minification: eight; original Nift threads −1.
Memory boundary
GNU time’s individual process/phase maxima; the page shows their five-run median. Not aggregate simultaneous pipeline RSS.
Toolchain
Nift 4.7.2 unchanged; Hugo extended 0.163.0; Node 24.21.0 / npm 11.19.0; Python 3.14.4. Standalone Go 1.26.0; upstream declares 1.26.8.
Full publication
Force content generation, Nift composition, analysis/downloads, human minification and search. Conditional copying of unchanged assets is retained. Frontend compilation and maintained source work differ between architectures.
10 / evidence
Open the repositories. Reproduce the work.
Frozen revisions and retained evidence make the claims inspectable. The experiment repositories were left unchanged while publishing this report.
Run from the docker checkout, with both projects as siblings.
Prepare pinned tools/dependencies using the README build guides before measuring. Use new evidence directories; retain accepted samples. Run sequentially:
The publication entry point is python3 scripts/build.py; use --all for forced full builds. Direct nift build composes already-prepared fragments only. Browser capture uses the documented pinned environment.