How Camunda Docs Handle Canonicals

By default, Docusaurus applies a self-referential canonical to every page. According to John Mueller, SEO advocate from Google, truly self-referential canonicals "do nothing". If the visited URL is different from the canonical, in which case it isn't truly self-referential, then it can be helpful. Query string parameters are a typical use case where the visited URL doesn't match a self-referential canonical.

In our versioned documentation, we don't use query string parameters, and every self-referential canonical is truly self-referential. This does nothing to help search engines identify the canonical version of your documentation, and from my experiences solving SEO problems with the Camunda 7 docs, this can potentially nudge search engines to select old versions of documentation as canonical.

Docusaurus also claims to offer the ability to specify a canonical URL in the frontmatter of a page, but at the time of my investigation I found this to be non-functional.

Our solution

The solution we've settled on is more complex behind the scenes, but not complex to use. For each document, we look for a frontmatter declaration of the canonical document. If that is specified, we look for that document and construct a canonical URL for it. If it isn't specified, we inspect all versions of the documentation for the newest document with the same path as the one being rendered. I think of each doc as being in a stack, with the top of the stack being the newest version of the document, or the newest version before it was moved somewhere else. Each version of the stack below the top will point a canonical reference at the document on top of the stack.

Here are some links to help you dig deeper into our approach:

• Guide for specifying canonical sources in our docs.

• How our system identifies a canonical source

• Unit tests describing the canonical identification logic.

• All the code you need to handle canonicals like the Camunda docs do.

• Pull requests:

  • Initial implementation of the canonical logic. Warning, it contains a regular expression that crashes in Safari!
  • Fixing the crashing regular expression. Again, this one is still not correct, and spams the build output!
  • Fixing the regular expression for good.