Google Search Console complains about a bunch of documentation pages with this status:
Alternate page with proper canonical tag
These pages aren't indexed or served on Google
AFAIK the canonical metatag is present, but the issue is that we use /docs/stable/ as a moving alias from the website while the canonical points to the versioned URL, eg:
https://openwisp.io/docs/stable/radius/user/enforcing_limits.html
- canonical:
https://openwisp.io/docs/25.10/radius/user/enforcing_limits.html
So Google is doing the right thing, but this means the URLs we link from the website are treated as alternate pages and not indexed.
I think we should use a moving canonical alias for the latest stable docs. We can also rename stable to latest, which seems more standard.
Expected behavior
For the current stable version, canonical URLs should point to /docs/latest/, eg:
/docs/latest/radius/user/enforcing_limits.html
/docs/latest/radius/user/generating_users.html
/docs/latest/firmware-upgrader/developer/
Older versions should keep pointing to their versioned URLs, eg:
/docs/24.11/...
/docs/22.05/...
dev should also keep pointing to /docs/dev/....
Implementation plan
In _templates/layout.html, make the canonical version segment conditional:
- if
current_ow_version == stable_version, use latest
- otherwise use
current_ow_version
Also normalize index.html pages in canonical URLs, so pages like:
/docs/latest/firmware-upgrader/developer/
canonicalize to the directory URL, not to:
/docs/latest/firmware-upgrader/developer/index.html
In build.py, create a /docs/latest alias to the stable version instead of, or in addition to, /docs/stable.
Since /docs/stable is already used from the website and may be linked elsewhere, we should not break it. If the hosting setup allows it, redirect /docs/stable/... to /docs/latest/...; otherwise keep /docs/stable as a compatibility alias, with canonical URLs pointing to /docs/latest/....
Notes
This doesn't seem too complicated. The main change is in the canonical URL template and in the build step which creates the moving alias.
Google Search Console complains about a bunch of documentation pages with this status:
AFAIK the canonical metatag is present, but the issue is that we use
/docs/stable/as a moving alias from the website while the canonical points to the versioned URL, eg:https://openwisp.io/docs/stable/radius/user/enforcing_limits.htmlhttps://openwisp.io/docs/25.10/radius/user/enforcing_limits.htmlSo Google is doing the right thing, but this means the URLs we link from the website are treated as alternate pages and not indexed.
I think we should use a moving canonical alias for the latest stable docs. We can also rename
stabletolatest, which seems more standard.Expected behavior
For the current stable version, canonical URLs should point to
/docs/latest/, eg:/docs/latest/radius/user/enforcing_limits.html/docs/latest/radius/user/generating_users.html/docs/latest/firmware-upgrader/developer/Older versions should keep pointing to their versioned URLs, eg:
/docs/24.11/.../docs/22.05/...devshould also keep pointing to/docs/dev/....Implementation plan
In
_templates/layout.html, make the canonical version segment conditional:current_ow_version == stable_version, uselatestcurrent_ow_versionAlso normalize
index.htmlpages in canonical URLs, so pages like:/docs/latest/firmware-upgrader/developer/canonicalize to the directory URL, not to:
/docs/latest/firmware-upgrader/developer/index.htmlIn
build.py, create a/docs/latestalias to the stable version instead of, or in addition to,/docs/stable.Since
/docs/stableis already used from the website and may be linked elsewhere, we should not break it. If the hosting setup allows it, redirect/docs/stable/...to/docs/latest/...; otherwise keep/docs/stableas a compatibility alias, with canonical URLs pointing to/docs/latest/....Notes
This doesn't seem too complicated. The main change is in the canonical URL template and in the build step which creates the moving alias.