Until recently, every topic posted here in the docs category generated a published page at docs.snapcraft.io automatically (after a small delay), regardless of whether it was actual documentation or not. The URL was derived from the topic’s title.
For example: https://forum.snapcraft.io/t/getting-started/3876 became https://docs.snapcraft.io/getting-started.
This created a couple of issues:
- we didn’t want every single topic published (such as this one, for instance)
- we didn’t always want the topic title to be the URL
To solve these issues, we’ve implemented a lookup table that lists the pages we want published from this category (by topic) and the URL we want for these topics (path).
You can see this table by unfolding the URLs on the new Snap documentation page.
This solves the above problems by:
- only publishing pages in the table
- allowing topic-derived URLs to be overridden
One disadvantage is that there’s now an added manual step required to publish pages on docs.snapcraft.io. To do this, ping me (@degville) as a comment and I’ll make sure it’s added to the table. I’ll also keep on top of new pages and add them when I find them.
You also need to be careful when linking to pages that may not be in the URL table. If the page isn’t on docs.snapcraft.io, use the complete URL to the forum post until it’s published on docs.snapcraft.io. We’ll try to automate this.
Let me/us know if you encounter any problems with the new process, such as broken or missing links (we’ll fix the broken links on the snapd roadmap page).