DOC-3497 - Fix self-referencing canonical URLs via page-aliases on v8

[kemister85]

Ticket

DOC-3497 / TINY-14151

Site

Inspect this page

• latest/react-cloud
  Notice it points to <link rel="canonical" href="https://www.tiny.cloud/docs/tinymce/latest/react-cloud/"> which is expected.
  then inspect this 5/react notice it now points to <link rel="canonical" href="https://www.tiny.cloud/docs/tinymce/latest/react-cloud/"> and not <link rel="canonical" href="https://www.tiny.cloud/docs/tinymce/5/react/">

Changes

Adds :page-aliases: to 14 pages on the tinymce/8 branch to claim the old page IDs from v5/v6. This allows Antora to resolve the correct canonical URL for older versions that were renamed or restructured in v6+.

Without these aliases, Antora cannot match the old page IDs to their v8 equivalents and falls back to self-referencing canonicals — causing Google to treat legacy pages as authoritative.

Framework integrations (8 pages):

• react-cloud.adoc claims react.adoc
• vue-cloud.adoc claims vue.adoc
• svelte-cloud.adoc claims svelte.adoc
• webcomponent-cloud.adoc claims webcomponent.adoc
• rails-cloud.adoc claims rails.adoc
• django-cloud.adoc claims django.adoc
• bootstrap-cloud.adoc claims bootstrap.adoc
• laravel-tiny-cloud.adoc claims laravel.adoc

Plugin/feature pages (6 pages):

• copy-and-paste.adoc claims paste.adoc
• cloud-quick-start.adoc claims quick-start.adoc
• spelling.adoc claims spellchecker.adoc
• non-editable-content-options.adoc claims noneditable.adoc
• advanced-templates.adoc claims template.adoc
• exportpdf.adoc claims export.adoc

Each change is a single :page-aliases: line addition; no content changes.

Note: The canonical fix requires a full multi-version build (v5 + v6 + v8) to verify — single-branch staging previews will show self-referencing canonicals regardless. Verify on production after merge by checking the <link rel="canonical"> tag on e.g. /docs/tinymce/5/react/.

Replaces: #4118 (v5) and #4119 (v6) — the page-aliases approach on v8 fixes canonicals for all older versions from a single branch.

Ref: Antora canonical URL docs

[MitchC1999]

Glad this worked! Do we need to do the same for 6 or 7?

[kemister85]

Glad this worked! Do we need to do the same for 6 or 7?

No, v6 and v7 already use the same filenames as v8 (e.g. react-cloud.adoc), so Antora naturally resolves their canonical to the v8/latest version. The problem was only with v5 pages that were renamed (e.g. react.adoc) — Antora couldn't find a newer version of those page IDs. The :page-aliases: on v8 claims those old IDs so Antora can resolve them. No changes needed on v6 or v7.

One thing to note: these aliases need to be carried forward whenever a new major version branch is created (e.g. tinymce/9). If v9 becomes the latest but doesn't have the aliases, the v5 canonicals would point to /tinymce/8/react-cloud/ instead of /tinymce/latest/react-cloud/ which now becomes a maintenance issue 😭.

[MitchC1999]

One thing to note: these aliases need to be carried forward whenever a new major version branch is created (e.g. tinymce/9). If v9 becomes the latest but doesn't have the aliases, the v5 canonicals would point to /tinymce/8/react-cloud/ instead of /tinymce/latest/react-cloud/ which now becomes a maintenance issue 😭.

That should be fine by default since each major is branched from the previous. I was just asking since I can navigate to latest/react-cloud from 5/react, but not 6 or 7. Nor can I go from 8 to 5. Perhaps we should keep the aliases on every branch, and add react-cloud as an alias for 5?

[kemister85]

One thing to note: these aliases need to be carried forward whenever a new major version branch is created (e.g. tinymce/9). If v9 becomes the latest but doesn't have the aliases, the v5 canonicals would point to /tinymce/8/react-cloud/ instead of /tinymce/latest/react-cloud/ which now becomes a maintenance issue 😭.

That should be fine by default since each major is branched from the previous. I was just asking since I can navigate to latest/react-cloud from 5/react, but not 6 or 7. Nor can I go from 8 to 5. Perhaps we should keep the aliases on every branch, and add react-cloud as an alias for 5?

Good point that branching handles the carry-forward naturally.

On the version selector, unfortunately page-aliases don't connect versions in the page version selector (Antora explicitly documents this limitation). They only handle redirects and canonical URL resolution. The version selector only links pages that share the same page ID (filename) across versions, so v5's react.adoc won't appear in the selector for v6+react-cloud.adoc regardless of aliases.

Adding react-cloud as an alias on v5 would create a redirect from /5/react-cloud/ → /5/react/, but it won't fix the version selector. It could be useful if anyone hits /5/react-cloud/ by manually editing the URL, but that's about it.

Personally I don't think that's worth the added complexity.

[ShiridiGandham]

LGTM