NIFT LABSAll experiments ↗

Experiment 04 / Docker Docs / October 2026

Same docs.
A different
build.

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.

READ THE BUILD01 Proof02 Sources03 Measurements06 Maintenance

01 / parity

Earn parity. Then measure.

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.

Read the complete parity scope ↗

02 / architectures

Two source models. One publication.

The distinction is intentional: the agent-primary pipeline has less transformation work because rendered HTML is maintained source.

HUMANS + AGENTS

docker

Keep the authored source.

  1. Maintained Markdown Frontmatter + structured CLI/API sources
  2. Docker compatibility renderer Standalone Goldmark / Chroma + bounded ports
  3. Transient HTML Generated bodies, never the editorial source
  4. Nift composition Raw HTML + shared layouts + explicit dependencies
  5. Publication + search Minification, downloads, metadata, feeds, Pagefind
AGENTS IMPLEMENT / HUMANS DIRECT

docker-agent

Maintain the rendered content.

  1. Maintained HTML Rendered bodies + associated typed metadata
  2. Nift composition Raw HTML + shared layouts + explicit dependencies
  3. Publication + search Downloads, metadata, feeds, Pagefind

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

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

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

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 initial21.83s optimized

docker-agent / warm full

30.27s initial14.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 stagedockerdocker-agent
Docker compatibility6.350 s—
Shared shell2.683 s—
Composition preparation—3.535 s
Joint body analysis2.420 s2.527 s
Nift composition2.852 s3.229 s
HTML minification1.806 s—
Download write0.072 s0.070 s
Ancillary publication0.264 s0.154 s
Assets0.036 s0.039 s
Pagefind preparation + index3.831 s4.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.

Initial versus optimized component evidence ↗

05 / changed inputs

An edit is a different workload.

Iteration peak memory / RSS

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
Changedockerdocker-agent
1 body9.23 s5.13 project + 4.05 searchRange 9.00–9.31 s6.43 s2.59 project + 3.92 searchRange 6.34–6.66 s
10 bodies9.64 s5.37 project + 4.21 searchRange 9.14–9.98 s7.10 s2.82 project + 4.28 searchRange 6.64–10.78 s
100 bodies11.26 s6.96 project + 4.31 searchRange 10.56–11.38 s7.40 s3.29 project + 3.87 searchRange 6.99–7.75 s
Shared footer16.27 s12.49 project + 3.95 searchRange 15.59–17.92 s12.18 s8.33 project + 3.85 searchRange 12.01–12.78 s
Navigation label13.95 s9.62 project + 4.25 searchRange 12.80–16.45 s10.55 s6.60 project + 3.99 searchRange 10.32–11.22 s
Title metadata9.20 s4.80 project + 4.28 searchRange 8.58–10.01 s6.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.

Peak RSS in MiB · accepted timings unchanged
CaseNift dockerNift docker-agent
1-page390.8389.8–393.3393.0392.7–394.6
10-pages391.7390.4–392.2391.6390.6–391.9
100-pages391.9389.7–392.5392.3392.0–392.5
layout425.4425.0–425.8392.3391.2–392.7
navigation392.1391.1–393.3391.9391.3–392.4
metadata392.2391.6–392.7391.6391.4–392.0
Peak RSS in MiB · accepted timings unchanged
CaseUpstream Hugo production
Upstream Hugo / 1-page1,425.01,378.5–1,512.6
Upstream Hugo / 10-pages1,433.81,368.8–1,584.1
Upstream Hugo / 100-pages1,488.41,340.4–1,549.1
Upstream Hugo / layout1,487.61,408.2–1,577.9
Upstream Hugo / navigation1,490.81,375.4–1,537.7
Upstream Hugo / metadata1,543.61,433.0–1,557.1

Different scopes and hosts remain separate; full-build memory is not substituted for an edit. Raw measurements, provenance and memory scopes ↗

06 / maintenance

Choose what you want to maintain.

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:

python3 benchmarks/run.py --projects docker,docker-agent --repetitions 5 --output ../docker-rerun/warm
python3 benchmarks/changed.py --repetitions 5 --output ../docker-rerun/changed
python3 benchmarks/fresh.py --projects docker,docker-agent --repetitions 5 --output ../docker-rerun/fresh
python3 benchmarks/routes.py --output ../docker-rerun/routes

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.