Content only available in english

2022.03.02 - How not to break links

Currently the path (wich is the vuepress id) for a content is based on the hierarquy to the content.

This approach has several benefits but one drawback. Since it's very easy to change content from folder to folder, and because in the beginning you still don't have a strong opinion on the structure to use, this moving of content place happens frequently. Unfortunatly this action breaks any existing link that might have been created within the diferent contents.

Alternative of changing the path source field

One solution to fix this would be to base the id on the instanceId of the record. This approach would maintain the link whatever the path might be.

Advantages	Disadvantages
Higher secrecy on the scope of a content	poorer reading ability of the link
Restructuring content path would maintin links	less actractive for newcomers, who won't value the solution it allows
path would be: /12742/ /pt/12742/ /es/12742/ etc	path would be: /cob/about/ /pt/cob/about/ /es/cob/about/ etc

The options to implements this would be:

1. change the definition so that path uses the id
2. change the vuepress page generators to the use the instanceId - it would mean changing getVuePressDoc.groovy, getVuePressSidebarConfig.groovy, references.js (both plugin and component) and problably some aditional files

Alternative of changing the markdown-it link processor

We could also change the evaluation of the markdown and allow editors to write links using the id (something like [link](12341) and whenever we detect a link based on just a number, we would replace by its full path. To do this we would extend markdown-it in the config.js file like this:

module.exports = async function() {
    ...
    return {
				...
        markdown: {
            extendMarkdown: md => {
                md.use(require('markdown-it-replace-link'), {
                    replaceLink: function (link, env) {
                        if(link ~= /^\d+$/) {
                            return 'path to id';
                        } else {
                            return link;
                        }
                    }
                })
            }
        }

Conclusion

Since there's no clear winner, and it would involve some changes we opted for mantaining the current solution.