Move a documentation page

A page's identity is its path. Other pages, sidecars and the sources name a page by that path. If you move or rename a page by hand, every one of those references breaks.

Do not move a page with git mv or a file manager. Use helpbuild --move. It moves the page and rewrites every reference to it in one step.

The whole routine

Build the tool, then run the commands from the repository root. debug/helpbuild/helpbuild is the tool's path with no output.dir (The build convention):

kiln build src/tools/helpbuild
debug/helpbuild/helpbuild --move <from> <to>
debug/helpbuild/helpbuild --move <from> <to> --apply --note "<why the page moved>"
debug/helpbuild/helpbuild --check-links content/doc

<from> and <to> are page paths relative to content/doc/published. Write them with no .md and no /index.md. For example, howto/development/regenerate-icons.

1. Run the move without --apply. This is a dry run, and it writes nothing.
2. Read each line of the dry run.
3. Run the move again with --apply.
4. Run the link check. It must report no broken link.
5. Run every suite whose file the move changed.
6. Commit the moved page, the changed files and the move record together.

Read the dry run

The dry run prints one line for each change, then a summary line:

rename content/doc/published/howto/development/regenerate-icons -> content/doc/published/howto/development/icons/regenerate
link content/doc/published/howto/development/index.md:43: regenerate-icons -> icons/regenerate
link content/doc/published/howto/development/regenerate-icons/index.md:14: ../kiln/index.md#the-build-convention -> ../../kiln/index.md#the-build-convention
record content/doc/publishing/moves.yaml: howto/development/regenerate-icons -> howto/development/icons/regenerate
helpbuild --move: 16252 files, 13 changes (dry run, nothing written)

The first word of each line is the kind of change:

• rename — the page and its sidecar get the new path. A folder page moves with its whole folder.
• link — a relative link that points to the page, or a link inside the page that its new depth changes. Sidecar url: values are links too.
• cross-ref — a sidecar cross reference documentation/<path>.
• literal — a string in src/ or test/ that names the page path, for example the help page of a window.
• record — the entry in the move record.

A literal change needs a careful read. The tool cannot tell a real page path from test data that names the same path. If a test fixture names the page, the move changes the fixture too. Run that suite after the move.

The move record

content/doc/publishing/moves.yaml holds one entry for each page that moved, from its first path to its last. The website makes its redirects from this record, so an old address still finds the page. The record is never pruned.

Do not edit the move record by hand. helpbuild --move writes it. The --note text becomes the entry's commit-note. With no --note, the tool writes a default note.

Plan moves from the page apps

Each page declares its apps in its sidecar, as global.apps. A page of one app belongs in the folder of that app. This command prints the moves that put each page there:

debug/helpbuild/helpbuild --plan-moves

It prints one <from> <to> line for each move, and each conflict on the standard error. It moves nothing. Read the plan, then apply each move that you agree with, one --move at a time.

After the move

The help remembers the last page that it showed. If that page moved, the help opens its home page instead.