962 routes. Retained React islands. Two maintained source models.
A production-scale Temporal documentation migration from Docusaurus to Nift composition. Preserve the publication, test the dependency boundaries, then measure the complete workflow.
Independent Nift Labs research. No Temporal endorsement. No Nift core or migration-template changes.
Event 001 / architectures
Three implementations. Two Nift source models.
Upstream Temporal Docusaurus is the original implementation. Nift temporal (authored-source) and Nift temporal-agent (rendered-source) are independent migrations with different maintained inputs.
React remains where appropriate. The authored path uses the pinned MDX compiler and retained components; the rendered path maintains finished HTML and initial island markup. This is a corpus-bounded migration, not a general Docusaurus replacement.
Event 002 / parity
First, preserve the site.
962HTML routes
793primary documentation pages
832ancillary Markdown/text/sitemap products
1,130retained non-framework assets
792maintained unique OG cards
567redirect rules
All 962 route semantic projections pass. All 4,544 highlighted code blocks match. Ancillary products and retained assets preserve accepted bytes, with no new missing local targets.
Each migration passed 132 browser states and 49 interaction observations, then reproduced from fresh public clones. Across 32 screenshot comparisons, 21 are pixel-identical; the other 11 each differ in only 21 pixels, with maximum channel delta 1: tiny rasterization noise, not universal pixel identity.
Framework artifacts differ intentionally: the upstream publication has 3,984 files; each Nift publication has 2,996. The contract covers publication semantics, retained products/assets and behavior rather than identical framework bundle sets. Search UI uses local transport fixtures; live Algolia/backend services were not exercised. Mermaid behavior is retained in the browser.
Event 003 / publication
Measure the whole publication.
Docusaurus puts up a respectable warm-full fight. Fresh state and unchanged publication tell a different story.
Scenario / seconds
Upstream Temporal Docusaurus
Nift temporal (authored-source)
Nift temporal-agent (rendered-source)
Warm full
34.1632.10–36.49
26.0525.73–26.09
10.3510.15–10.50
Fresh application state
289.64289.35–341.44
26.4425.94–29.09
10.6110.35–15.73
Unchanged normal command
44.6434.81–48.79
1.771.56–2.17
1.321.01–1.52
Five serialized samples per cell; median above observed min–max range. Active shared host; OS caches uncontrolled. Installed dependencies retained and acquisition excluded.
Warm full publication
02040 s
Upstream Temporal Docusaurus34.16 s
32.10–36.49 s · five samples
Nift temporal (authored-source)26.05 s
25.73–26.09 s · five samples
Nift temporal-agent (rendered-source)10.35 s
10.15–10.50 s · five samples
Fresh application state
0160320 s
Upstream Temporal Docusaurus289.64 s
289.35–341.44 s · five samples
Nift temporal (authored-source)26.44 s
25.94–29.09 s · five samples
Nift temporal-agent (rendered-source)10.61 s
10.35–15.73 s · five samples
Unchanged publication loop
02550 s
Upstream Temporal Docusaurus44.64 s
34.81–48.79 s · five samples
Nift temporal (authored-source)1.77 s
1.56–2.17 s · five samples
Nift temporal-agent (rendered-source)1.32 s
1.01–1.52 s · five samples
Scenario definitions and cohort boundaries
Warm full: complete upstream yarn build; Nift force recomputation of conversion, bundles, projections and composition.
Fresh application state: generated application caches/output cleared; dependencies retained. Nift maintained OG source assets remain. This is not machine-cold.
Unchanged: complete normal production command with unchanged maintained inputs.
Upstream warm-full and unchanged use the same command, in separate chronological cohorts. Their differing medians reflect observed cohort variation, not different build algorithms. Docusaurus development server/HMR is not measured.
Event 004 / ownership
Fresh state exposes asset ownership.
OG cache / explicit maintenance
258.8s median upstream OG render duration
Clearing upstream application state also clears the OG cache. Its plugin regenerates the cards. Both Nift projects maintain the 792 unique accepted cards as static assets: normal publication copies them, and intentional metadata/title changes use an explicit selective refresh workflow.
Nift did not generate 792 cards in 26 seconds. The fresh-state result includes an intentional change in asset ownership.
Upstream also reclones the public cookbook during every prebuild. Authored Nift keeps a pinned maintained local snapshot; updating it is explicit maintenance. Upstream network acquisition remains visible in its complete command.
Event 005 / iteration
The feedback loop is the daily 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.
Maximum individual process/phase RSS; sampled tree sums remain separate in the tables
01,000 MiB
body-1
Nift authored890.1 MiB
Nift rendered153.6 MiB
body-100
Nift authored891.0 MiB
Nift rendered153.9 MiB
metadata
Nift authored578.8 MiB
Nift rendered220.8 MiB
shared-layout
Nift authored915.0 MiB
Nift rendered548.1 MiB
navigation
Nift authored898.1 MiB
Nift rendered776.7 MiB
island-source
Nift authored930.0 MiB
Nift rendered791.9 MiB
route-rename
Nift authored990.5 MiB
Nift rendered756.6 MiB
Changed-input: single original observations. Unchanged: five-sample median [min–max]. Sampled ~50ms sums can double-count shared pages, miss peaks and are not PSS. Explicit maintenance memory is outside publication. Full case tables and evidence below retain the other scopes and workloads.
Developers and agents usually change a few pages, metadata fields, diagrams, navigation entries or components. Iteration matters as much as full publication.
Selected publication observations / seconds · single cases
One page
Authored6.113s
Rendered1.113s
100 pages
Authored8.684s
Rendered1.214s
Navigation
Authored19.462s
Rendered11.156s
Island source
Authored17.215s
Rendered10.956s
Route rename
Authored29.752s
Rendered11.403s
Selected lanes use a shared zero-origin 0–32s scale. The complete table and maintenance boundaries follow.
Change
Nift authored-source
Nift rendered-source
body-1
6.113s
1.113s
body-10
6.467s
1.059s
body-100
8.684s
1.214s
metadata
4.086s
1.465s
shared-layout
8.877s
9.941s
navigation
19.462s
11.156s
diagram
6.020s
0.959s
generated-synced
5.706s
1.059s
search-visible
5.707s
1.059s
island-source
17.215s
10.956s
route-add
29.386s
11.709s
route-rename
29.752s
11.403s
route-delete
30.054s
11.302s
All 26 changed-input/lifecycle publications matched independent forced recomputation. These are single observations per case, not five-sample medians.
Representative upstream production rebuild observations: body edit 40.249s; navigation 37.885s. They do not measure Docusaurus HMR.
Publication versus maintenance-inclusive operations
Metadata publication excludes explicit OG refresh: whole operations were 4.936s authored and 2.144s rendered. Rendered island-source work includes explicit initial-markup maintenance; whole operation 12.229s versus 10.956s publication. Authored island-source 17.215s already includes its derived work.
Route-add OG setup occurred outside publication timing; no whole-operation duration is claimed. Rendered fixtures coordinate HTML, downloads and LLM views rather than deriving those views automatically. Explicit maintenance memory is outside publication RSS.
Shared layout and navigation still fan out. Rendered source is not uniformly faster: shared layout costs 9.941s versus authored 8.877s. Route lifecycle work remains substantial, and these are future profiling targets.
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.
Maximum individual process/phase RSS and separate sampled descendant resident-page sum; these are different scopes. Changed-input: single original observations. Unchanged: five-sample median [min–max]. Sampled ~50ms sums can double-count shared pages, miss peaks and are not PSS. Explicit maintenance memory is outside publication.
Peak RSS in MiB · maximum individual process/phase · accepted timings unchanged
Case
Nift authored
Nift rendered
unchanged
284.4278.3–288.6
154.8153.3–156.8
body-1
890.1
153.6
body-10
893.9
156.4
body-100
891.0
153.9
metadata
578.8
220.8
shared-layout
915.0
548.1
navigation
898.1
776.7
diagram
890.9
153.0
generated-synced
902.4
153.7
search-visible
883.8
151.9
island-source
930.0
791.9
route-add
985.4
782.6
route-rename
990.5
756.6
route-delete
964.8
770.8
Peak RSS in MiB · sampled descendant resident-page sum · accepted timings unchanged
Case
Nift authored
Nift rendered
unchanged
286.1281.8–295.8
152.2146.0–156.9
body-1
1,156.7
153.0
body-10
1,172.8
159.6
body-100
1,393.6
184.3
metadata
594.9
229.9
shared-layout
959.7
597.2
navigation
1,092.9
856.7
diagram
1,169.1
152.1
generated-synced
1,138.8
150.7
search-visible
1,148.4
151.3
island-source
1,082.8
869.3
route-add
1,495.0
859.3
route-rename
1,475.4
829.6
route-delete
1,478.6
847.9
Peak RSS in MiB · maximum individual process/phase · accepted timings unchanged
Case
Upstream
Upstream body production
6,949.8
Upstream navigation production
6,932.8
Peak RSS in MiB · sampled descendant resident-page sum · accepted timings unchanged
Initial five-sample warm-full medians were 37.867s upstream (35.153–40.636), 27.366s authored (26.259–30.420), and 11.434s rendered (9.905–13.016).
Faithful implementation → profile → tighten dependencies/caches → inject corruptions and test repair → revalidate parity → final benchmark
T8 fixed a real stale transitive imported-MDX TOC case affecting two pages. Eleven corruption-repair cases tested retained caches and products. Initial and rejected evidence remain available: optimization only counts after replaying the correctness gates.
Shared shell work, route/catalog invalidation, projection generation and component bundling remain costs. Some final rendered shared-change observations are slower than their initial probes; the result is evidence for future tooling work, not a promise that every row improves.
Event 007 / memory
Less measured memory, with the scopes attached.
Maximum individual process/phase RSS
037507500 MiB
Upstream Temporal Docusaurus6,945.71 MiB
6,895.61–6,971.68 MiB · five samples
Nift temporal (authored-source)949.25 MiB
943.87–963.26 MiB · five samples
Nift temporal-agent (rendered-source)773.18 MiB
763.74–791.98 MiB · five samples
Sampled descendant resident-page sum peak
037507500 MiB
Upstream Temporal Docusaurus7,039.11 MiB
6,986.77–7,063.38 MiB · five samples
Nift temporal (authored-source)1,464.16 MiB
1,438.80–1,494.47 MiB · five samples
Nift temporal-agent (rendered-source)851.88 MiB
842.52–873.25 MiB · five samples
Warm-full five-sample medians and observed ranges. Maximum individual process/phase RSS is not aggregate memory. The sampled descendant sum polls about every 50ms, can double-count shared pages, can miss short peaks, and is not PSS. Explicit maintenance operations are outside these publication measurements.
Event 008 / components
Composition is a small part of the pipeline.
Nift temporal (authored-source)
Component
Median seconds
browser bundle
1.977
local cookbook inputs
0.077
markdown downloads or static
1.671
markdown mdx
10.124
nift composition
0.330
react ssr or html source
2.621
retained components server bundle
2.296
shell and dependencies
6.152
sitemap
0.041
source catalogue and context
0.241
static and browser publication
0.134
Nift temporal-agent (rendered-source)
Component
Median seconds
browser bundle
1.967
markdown downloads or static
0.110
nift composition
0.318
react ssr or html source
0.514
retained components server bundle
0.863
shell and dependencies
6.120
sitemap
0.038
static and browser publication
0.121
The authored path spends about 10.12s in Markdown/MDX, 6.15s in shell/dependencies, 2.30s in the component server bundle, 2.62s in React SSR and 1.67s deriving Markdown downloads. Rendered source avoids routine Markdown conversion but retains shared shell and browser-bundle work.
These are complete publication workflows, not bare Nift composition or native markup-renderer timings. Nift composition is about 0.33s authored and 0.32s rendered. Phase medians do not add exactly to command medians; startup/preparation and unattributed work remain.
Event 009 / maintenance
Three codebases, three ownership tradeoffs.
Upstream Temporal Docusaurus
Established ecosystem, conventional Docusaurus/React tools, native component workflow and familiar contributor model.
Higher measured publication time and memory, expensive fresh-state work and broader production rebuilds.
Nift temporal (authored-source)
Markdown/MDX/frontmatter and structured references stay authoritative. Companion products derive automatically; explicit dependencies and retained React islands support faster production iteration.
Owns a bounded project compiler/cache/island adapter layer. Shared runtime and navigation changes still fan out.
Nift temporal-agent (rendered-source)
Fastest publication and very cheap body iteration; fewer routine transformations.
Maintainers coordinate HTML, initial island markup, downloads, LLM projections, metadata and navigation. Those representations can drift without explicit validation.
Event 010 / opinion
Prefer authoritative source for maintenance.
Agents implement, humans direct
Preferred: Nift temporal (authored-source)
One authoritative Markdown/MDX/frontmatter source derives companion products. Rendered-source speed does not outweigh the coordination burden. Publication time and measured memory improve over upstream, while retained React islands preserve practical interaction.
Humans and agents both edit
Preferred: Nift temporal (authored-source)
Human-readable source, reviewable diffs and familiar content organization. The iteration loop is fast enough, and fewer synchronized representations make maintenance easier.
Even if migration effort and incumbency were removed, Codex still prefers Nift temporal (authored-source) for both scenarios. This is an engineering judgement among all three implementations, not a benchmark-derived universal rule.
Event 011 / evaluation
A serious evaluation from Docusaurus to Nift.
The evidence supports Temporal seriously evaluating a migration from Docusaurus to Nift with retained React islands.
It does not establish an unconditional migration recommendation. Live search/backend/deployment integration, editor and component workflows, adapter/library upgrades and long-term compatibility ownership need evaluation. Docusaurus ecosystem benefits remain real.
Event 012 / guidance
Dogfood the migration guidance.
nift init --migration was used as intended; an older manual playbook did not replace it. No Nift core or migration-template changes were made.
Future guidance candidates: explicit transitive dependency inventories, route/catalog invalidation, shared-shell fan-out, projection ownership, island/OG maintenance and adapter review. Keep those proposals separate from this accepted migration.
Event 013 / methodology
Keep the measurement boundaries visible.
Five serialized samples for full/fresh/unchanged scenarios, rotating implementations on an active shared host. OS caches uncontrolled; fresh application state is not machine-cold.
Pinned sources, installed dependencies outside timing. Upstream cookbook network fetch remains inside its prebuild. Nift uses maintained OG assets and a pinned cookbook snapshot.
Changed-input cases are single observations, validated against independently forced output. Production publication is separate from unmeasured development/HMR.
Search UI parity uses fixtures; no live Algolia crawl/upload/backend claim. Deployment services were not benchmarked.
One upstream attempt returned success after a public GitHub HTTP/2 fetch failure produced an offline cookbook placeholder. Its wrong-corpus result was rejected; the unchanged exact command succeeded on retry without source changes. Raw log retained.
Complete Nift pipelines include project-side compilation, retained React, projections and publication. RSS scopes and excluded maintenance costs stay separate.
Use each migration README for pinned Node/Yarn/Nift prerequisites, dependency installation, normal/forced publication, explicit OG refresh and island-maintenance workflows. The final report records measured revisions, commands, source scope and acceptance gates.