FAQ permalink bug

[dichotommy]

FAQ permalink bug

Problem

Right-clicking a link in /learn/core_concepts/documents.md and opening it in a new tab results in a 404.

^ This link 404s if opened in a new tab

Many thanks to community Slack member Mubashirullah Durrani for spotting this problem 🙏🏻

Link to public Slack discussion: https://meilicommunity.slack.com/archives/C018KQ6HS77/p1640342335011700

Context

The use of permalinks for faq.md and open-api-readme.md has led to some 404s in the past, which we previously attempted to resolve. Clearly, this has not completely solved the problem.

The reason this link 404s is most likely because it uses the filepath (/resources/faq.md) instead of the permalink (/faq.html). However, while changing this link to /faq.html appears to fix the 404 problem, it also causes our CIs to fail for an unknown reason.

The cause of the bug may simply be an incorrect link, but the real problem here seems to be an interaction between our check-links CI and the way VuePress handles permalinks. As we are considering using permalinks to hide the .html extension, this may warrant further investigation.

Proposed steps

Although this will not solve the problem, I propose that we temporarily remove the permalinks from both faq.md and open-api-readme.md and instead use VuePress's built-in filepath-based links, until such time as we feel confident in the behavior of permalinks and our check-links CI.

Fully resolving this bug may not be a high priority for us, but we should nonetheless ensure a "bug-free" user experience on our site until such time as we can devote resources to it.