# Plan a documentation move without losing reader context

Canonical: https://githtml.com/guides/move-documentation-without-losing-reader-context
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Before moving documentation, identify who links to the current paths and how readers find the pages. Plan old-to-new mappings, preserve historical references, and verify navigation after the change. A successful move is not merely a tidy directory: readers must still reach the right instructions with enough context to recognize them.

## Define the reason for the move

State the reader problem the reorganization solves. Perhaps installation pages are scattered across package folders, or historical decisions appear beside current operating instructions. If the reason is only aesthetic, compare the benefit with the cost of maintaining existing links.

Choose a small representative group of pages before planning a repository-wide move. The sample should include a page with images, a page linked from elsewhere, and a page with important section anchors.

## Inventory link relationships

Create an old-path to new-path table in your planning notes. Search tracked files for each old path using git grep, and inspect navigation indexes, source references, and generated links. Remember that links in issue discussions or external websites may not appear in the repository search.

Record which links can be updated and which need a compatibility strategy appropriate to the hosting environment. A redirect available on a website is not automatically available inside a saved HTML document.

1. Create an old-path to new-path map.
2. Search tracked content for incoming links.
3. Verify deep links, section anchors, and relative assets after the move.

## Preserve version meaning

Keep commit-specific review links as historical evidence. Their purpose is to identify the old snapshot, not to follow the newest file location. For current instructions, update the maintained entry point and make the new title and path clear.

If a page also changes content during the move, review the structural and substantive changes separately. Otherwise a missing warning can hide among path updates, and reviewers may approve a relocation without noticing that instructions changed.

## Verify the new route

From the main index, follow the expected task route and check every moved page’s local images, relative links, and section destinations. Open a deep page directly as well as through navigation; readers frequently arrive without visiting the homepage.

For gitHtml copies, confirm that the intended .html files are present and readable after the owner’s normal repository update process. Keep a brief migration note listing the new entry points and any known broken external references that still require attention.

## Sources and further reading

- [Git: grep reference](https://git-scm.com/docs/git-grep)
- [MDN: HTML anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a)
- [GitHub: permanent file links](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)

## Related guides

- [Share a GitHub document at an exact revision](https://githtml.com/guides/share-permanent-github-document-links)
- [Choose branch, tag, or commit references for documentation](https://githtml.com/guides/choose-branch-tag-or-commit-for-documentation)
- [Read an older document without switching branches](https://githtml.com/guides/read-old-documentation-with-git-show)
- [Compare documentation between two releases with Git diff](https://githtml.com/guides/compare-documentation-between-two-releases)

Editorial approach: https://githtml.com/guides/about