You’d think an intuitive system for creating links between pages would be a central feature of every site generator. After all, that’s kind of what the web is all about. Sadly, it’s often an afterthought.
The current mechanisms tend to distract from writing. Each time you want to make a link to another page, you have to pause to compute a relative path and/or transform the path to a published URL in your head. If you move the page you’re editing, it may cause the relative path to shift, which means you have to go back and recompute those references.
It’s no wonder writers create broken links at an alarming rate or spend excessive amounts of time fixing broken links left behind by other writers. But we can’t fault the writers when it’s the system itself that’s broken. Let’s figure out a solution.
In a previous article, we established that content is sovereign, which means the site generator needs to gather content from various repositories and branches. In order for the generator to identify, aggregate, and catalog content partitioned in this way, the repositories must present a consistent structure. Otherwise, the generator isn’t going to know which files represent pages or which pages should be grouped together.
Ship your documentation as fast as your product.
We provide tools and workflows that help teams coordinate documentation initiatives across products and departments.
