docs: add canonical url headers

[AngeloDanducci]

Misc PR

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes Add canonical URL headers to resolve dual-deployment deduplication #840

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.

[AngeloDanducci]

@abrahamdaniels fyi https://www.mintlify.com/docs/optimize/seo#automatically-generated-meta-tags suggests canonical instead of canonicalUrl as in the original issue.

Tested via curl -s link | grep -o '<link rel="canonical"[^>]*>'

Also note that some links don't follow the current doc paths in the repo but they do match the live site, for now I've left the caonical refs to the current accurate live links but not sure if that should change.

[planetf1]

I think we need to match to the staging site -- that is representative of main, so should be a safe check assuming being rebased.

So I found these discrepancies:

Two blockers:

1. 12 canonicals point to redirect sources, not final destinations. The paths below use old URL prefixes (/guide/, /evaluation-and-observability/) that are configured as redirect sources in docs.json — they 301 to the new locations. A canonical should point to the final served URL, not an intermediate redirect. The correct paths (matching the docs.json nav entries) are:

   File	Current canonical	Should be
   how-to/act-and-aact.md	/guide/act-and-aact	/how-to/act-and-aact
   how-to/backends-and-configuration.md	/guide/backends-and-configuration	/how-to/backends-and-configuration
   how-to/evaluate-with-llm-as-a-judge.md	/evaluation-and-observability/evaluate-with-llm-as-a-judge	/how-to/evaluate-with-llm-as-a-judge
   how-to/generative-functions.md	/guide/generative-functions	/how-to/generative-functions
   how-to/m-decompose.md	/guide/m-decompose	/how-to/m-decompose
   how-to/tools-and-agents.md	/guide/tools-and-agents	/how-to/tools-and-agents
   how-to/working-with-data.md	/guide/working-with-data	/how-to/working-with-data
   observability/logging.md	/evaluation-and-observability/logging	/observability/logging
   observability/metrics.md	/evaluation-and-observability/metrics	/observability/metrics
   observability/telemetry.md	/evaluation-and-observability/telemetry	/observability/telemetry
   observability/tracing.md	/evaluation-and-observability/tracing	/observability/tracing
   reference/glossary.md	/guide/glossary	/reference/glossary

2. tutorials/03-using-generative-stubs.md canonical points to a different page. The canonical is set to .../tutorials/03-using-generative-slots, but that's an older, separate page with different content (the slots terminology predates the current stubs naming). The canonical should be https://docs.mellea.ai/tutorials/03-using-generative-stubs to match the file's own nav entry.

Two pages missed:

3. docs/docs/concepts/plugins.mdx — live nav page, no canonical added.
4. docs/docs/index.mdx — the site root, no canonical added. Should be https://docs.mellea.ai/.

[planetf1]

See inline comment - links need updating
See https://ibm-llm-runtime-aaf3a78b.mintlify.app/ for the staging site which is built from main after merge

[planetf1]

LGTM

[markstur]

LGTM

[AngeloDanducci]

Rebased in hopes of fixing those unrelated CI test failures.