Skip to content

Use latest alias as canonical URL for stable docs #283

@nemesifier

Description

@nemesifier

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions