Persistent Links via Frontmatter Page IDs / Permalinks (Git Sync)

[maksim-yesman-covergo]

The Problem: Link Rot During Documentation Refactoring
We currently use GitBook synced with a GitHub repository for our documentation. While Git Sync is fantastic for collaboration, relying strictly on file paths for routing creates significant friction: whenever we reorganize our documentation hierarchy, rename folders, or move .md files, the underlying file path changes.

This causes two major issues:

1. Broken Internal References: Hyperlinks between documents within GitBook break, requiring tedious manual updates across multiple files.
2. External Link Rot & SEO Loss: Customer bookmarks, shared links, and indexed search engine URLs are instantly invalidated.

Why Existing Redirects Don't Solve This for Git Sync:
While I am aware that GitBook supports URL redirects, this feature does not fit our workflow for two key reasons:

1. We work strictly in GitHub, not the GitBook UI: Because we author, refactor, and restructure our documentation directly in our IDE and push to GitHub as code, we miss out on any UI-based redirect automation.
2. Redirect accumulation is unmanageable: We do not want to manually maintain an ever-growing, error-prone list of redirects in our configuration files every time we clean up or rearrange our docs. It creates unnecessary technical debt and clutters our repository.

The Proposed Solution: Frontmatter Page IDs / Permalinks
It would be a massive improvement if GitBook supported a persistent identifier mechanism independent of the file path—similar to how Confluence handles Page IDs or Notion uses Block IDs.

Specifically, we would love the ability to define a static ID or permalink inside the YAML frontmatter of our Markdown files:

---
id: doc-unique-identifier-123
permalink: /guides/initial-setup
---

How it would work:

• Internal Linking: GitBook’s editor and parser could resolve links using the frontmatter id (e.g., [Setup Guide](id:doc-unique-identifier-123)) rather than relative file paths like ../../guides/setup.md.
• External Routing: If a file is moved from /drafts/setup.md to /v2/getting-started/installation.md in GitHub, GitBook would recognize the persistent frontmatter ID and resolve the route natively without us ever needing to touch a redirect configuration list.

Why This Matters to Tech Teams:

• True Docs-as-Code Flexibility: Teams can reorganize, rename, and clean up their repository structure directly in git without fearing broken links or managing cumbersome redirect tables.
• Better Git Sync Experience: It brings object-based CMS stability to a Git file-system workflow, removing the biggest drawback of docs-as-code.
• SEO & Bookmark Preservation: Ensures external visitors and search engines never hit a 404 page after a documentation cleanup.