Refactoring documentation without breaking it

Docs-as-code borrowed a lot from software engineering. Docs live in Git, go through review, run through CI, and ship as versioned sites. Most editors still treat a documentation project as plain text, so the moment you rename a heading, move a page, or split a topic, cross-links and anchors can break with nobody noticing until a reader hits a 404.

I'm a technical writer, and most of my open-source contributions are documentation work, so I keep meeting this problem from the inside. Recently I fixed a few links in the Fluree DB docs that 404'd because mdBook rewrites source .md links to .html but renders a README.md as index.html; a link check then surfaced more broken links across the site. In CocoIndex, I restored links that broke when a release branch was removed, and earlier added a lychee link-checking workflow to its docs CI. The projects and tools differ, but the failure is the same: change the structure, links rot, and CI tells you only after the damage is already public.

This lightning talk treats that as a refactoring problem, not only a writing or publishing one. I'll use Zensical Studio, a newly launched FOSS extension for VS Code, as a worked example of what editor-integrated docs tooling can do: flag broken links as you type, parse Python Markdown the way MkDocs and Zensical read it, and show every incoming link to a heading so one rename updates them all instead of leaving cleanup to CI.

1. Documentation has a refactoring problem that's separate from writing or publishing it. Renaming a heading or moving a page can break links, and most editors won't warn you.
2. Broken links and shifting anchors erode reader trust. CI catches them, but only after you push.
3. Editor-integrated tooling can make structural changes safer. I'll use Zensical Studio to show what that looks like in practice: in-editor broken-link diagnostics, Python Markdown awareness for MkDocs and Zensical, and renames that fix incoming links.