SEO

[fhennig]

Technical

Canonical links

Antora will set the canonical link of pages across versions to be the stable page. So the "Installation" page which exists in most versions will have the canonical link set to its stable version. It is debatable whether this is correct or not, there are other pages that don't do this and some that do.

In some cases, the page has very little edits across versions and it makes sense to define the stable version as the canonical one. In other cases, a page changed a lot and it is debatable whether the content is similar enough. Also the whole point of offering different versions of a document is that they have different content and the differences are important. So you can't just look at the stable docs for an older version of the software. This would be an argument against the canonical link setting in its current form.

I asked mojavelinux in the Zulip chat about this, and he said:

We fundamentally disagree here. We have been asked by just about every user to have the search engine prioritize the latest version. And that is the model we went with. If you don't see it this way, again, you have the freedom to write an Antora extension that does something differently. But we cannot change this model of the default behavior now in Antora (at least not outright). Too many users rely on it.

I'd also like to point out that Google is incredibly unclear about how to handle canonical URLs for versioned documentation. If they put out literature dedicated to that topic (I'm not holding my breath), and it differs from what we're doing in Antora, then I'd be open to revisiting this topic or making it a configuration setting.

I did find examples of other documentation pages that didn't use this canonical behaviour. Also I found this post interesting on the topic: https://webmasters.stackexchange.com/questions/99867/how-to-correctly-mark-up-different-versions-of-the-same-document-which-are-non-c

Sitemaps

The sitemaps contain links to pages which have then canonical URLs to different pages. For example Druid index 0.7 will link to Druid index stable as the canonical page, but both are in the sitemap. I've asked mojavelinux about excluding the "duplicate" pages from the sitemap and he said:

No, that is not currently possible. As far as I understand, what Antora is doing is the correct behavior. If you disagree, you are free to write an Antora extension that replaces the sitemap files.

Content

Titles are not unique

This should be fixed

Polish

I think some of our pages need more polishing, but this costs a lot of time. I would focus in particular on the main landing page as well as the Operator landing pages (example: NiFi). I think most other technical pages on stackable specifics are unlikely to rank highly on any query anyways.

• New documentation landing page #214
• Operator overview pages #282

[fhennig]

done!