# V1 to V2 migration

Migrate by building a separate, reviewed V2 reader, not by overwriting a working first-generation installation. Keep the old source, output and configuration until the new reader is checked live and you know how to restore the previous version.

This comparison is grounded in first-generation source and the V2 engine pinned for this handbook. Both package fields currently say 1.1.4; that string does not mean the engines are identical or establish a numeric 2.0 package release. Record repository and commit identifiers.

# What changes

The first-generation comparison below comes from inspected source, not claims copied from the old public website. A customized old installation can differ; inventory its actual revision and changes before transferring anything.

# What to transfer

Retain V2’s local library/font bundles and their licenses/notices. Port a necessary customization against the actual current template/CSS contract; do not copy an older template over the new one and assume its scripts/search/paths stay compatible.

Compatibility of a Markdown file is not proof that its route, rendering, template or editing permissions stay the same. Treat each of those as a separate check.

# 1. Inventory the old site before touching it

Record the old engine commit, Node version, build command and host/deployment process. Copy the intended Markdown, media, configuration and custom templates/styles into a recoverable backup. Preserve the previous rendered reader as a separate rollback snapshot.

Make a list of published URLs and the important links that point to them. Include home, section landings, deep pages, images and downloads. Old browser/editor data is not automatically compatible with a new account store. Do not copy dependency folders or arbitrary private files into the new reader.

If you cannot identify which directory contains source versus deployed output, stop and use Project map. Backing up only HTML is not a source backup.

# 2. Create a separate V2 installation

Use a new checkout with Node.js 24+ and npm ci. Select the intended V2 commit deliberately; this handbook documents the pinned engine revision shown in Complete setup.

Build the included V2 documentation first so a later error can be separated from an installation problem. Do not overlay the entire old project onto this checkout. Carry over only reviewed content/media and deliberate configuration/customization changes.

# 3. Transfer source without changing the old installation

Copy your intended Markdown into a dedicated review content tree. Preserve YAML frontmatter and section _index.md files. Bring public images/downloads into appropriate static paths. Keep private editor/account backups outside those public inputs.

A simple file might remain familiar:

---
title: Recovery checklist
description: Confirm a service is ready after a planned restart.
---

# Recovery checklist

## Verify the result

Check the service's expected health response and record the result.

Its filename does not alone determine its public URL. V2 builds routes from titles and section paths. Before/after route review is necessary even when the file contents did not change.

Old raw-HTML styling/embed tricks may render as text or no longer have the same behavior. Prefer supported Markdown where possible. Do not switch on raw HTML globally merely to make one old page look similar; review the security and compatibility tradeoff separately.

# 4. Build into a dedicated review output

npm run build -- --content ./migration-content --out ./migration-output

Create/review migration-content first. The output path is cleared by build, so it must be a disposable generated-output directory, never the old site/source/private data. File configuration/templates/static inputs still come from the V2 installation.

The bundled npm run serve serves default dist/, not this alternate directory. Use an appropriate HTTP server for the review output, or place the reviewed source into the intended V2 content location and build normal dist/ for its preview. Do not mistake an old preview for this migration build.

Fix YAML errors and duplicate-title URL collisions in source. Retest custom templates against V2’s actual placeholder and script expectations; old generated HTML is not a substitute for adapting source templates.

# 5. Check content and routes, not just build success

Walk each important old URL and identify its new destination. Stable routes are preferable when practical. For changed routes, plan supported host redirects and test the actual status/destination after deployment. This showcase’s Old URL map is an example of an explicit map, not an automatic migration feature.

Check page title, headings, tables, code copy, diagrams, images, downloads, internal links, search page/heading results, themes and phone-width layout. Look for collisions or broken anchors caused by punctuation/language title normalization. Do not assume all title scripts produce useful routes; the current limits are documented in Capabilities and limits.

# 6. Introduce editor accounts only if needed

The reader can remain file/Git-based. If you want V2 browser writing, create new intended accounts with supported commands and test section assignments on synthetic content first. No automatic first-generation account/content converter is claimed.

Keep the new private store outside reader output, select the same path for account commands and server, and verify an editor’s allowed and denied pages. Recheck saved/source/published/deployed boundaries before giving a team access.

# 7. Switch the reader with a return path

Review the exact generated upload and deployment controls. Keep the prior output and source backups. Deploy the new reader using your chosen host’s normal process, then inspect the real home/deep routes, assets, search, 404 and redirects.

A repository commit or provider success message is not the entire check. If the live result is wrong, decide whether the problem is content, output layout, host settings or caching before repeatedly pushing unrelated fixes.

Rollback must identify the exact old output and what private-data state is compatible. Restoring old HTML does not reverse account changes. Follow Upgrades and rollback for planning, and do not overwrite newer source/runtime data without knowing what you would lose.

# Migration completion checklist

• Old source/configuration/media and reader version remain recoverable.
• New engine revision and dependency/build procedure are recorded.
• Intended pages render and search correctly, with no private data exposed.
• Every important old link has a verified destination or redirect.
• Optional writers have tested role/section permissions.
• The actual live reader passes desktop/phone-width checks.

Only then retire obsolete deployments or backups according to your retention policy. The migration is a reviewed transition, not a blind folder copy.