Permalinks

[scottyeager]

From time to time we restructure the manual in a way that breaks links coming in from outside sources. Our own sites that link to the manual are of particular concern:

• threefold.io
• dashboard.grid.tf (including playground)
• ...?

Requiring updates to these other sites whenever the manual changes is a rather fragile arrangement. While we check links internal to the manual on every PR, checking links from external sites and requiring manual maintainers to be responsible for seeing that they are updated is asking too much, in my opinion.

Redirects

mdbook supports a redirect table that can be used to improve this situation. However, simply adding a redirect each time a link changes is not a manageable or sustainable solution.

Permalinks

Instead, I propose that we can add a small set of permalinks to the manual. These would cover the needs we have for ThreeFold sites that link to the manual and be guaranteed to always redirect to a valid and relevant manual link.

Here are a few possible examples:

manual.grid.tf/buy_tft
manual.grid.tf/deploy_getstarted
manual.grid.tf/farming_getstarted

Each would be setup with a single redirect to an appropriate page. If the target page is ever moved, all that's needed is to update the redirect accordingly.

Reference page

The final piece would be a reference page within the manual that embeds all current permalinks (maybe under the contribution section). This serves two purposes:

1. Provide a reference for anyone wanting to use these permalinks on other sites
2. Ensure that permalinks are checked by the link checker workflow. Thus manual contributors will be alerted if their changes break a permalink and can likewise update the appropriate redirect

[Mik-TF]

This is a very good idea but since we are soon moving the manual to the gitea git.ourworld.tf which is using hero mdbook, we won't be able to have permalinks easily with how hero mdbook works. Thus closing for now but we keep in mind to find a way to use permalinks with hero mdbook.

Thanks @scottyeager