Add canonical tags to API reference documentation

[asafashirov]

Fixes https://github.com/pulumi/marketing/issues/1240

Adds canonical link tags to all 1,621 static HTML files in the API reference documentation to resolve Google Search Console duplicate content warnings.

The issue affected 34 URLs that were being indexed with query parameters (?iaid, ?__hstc, etc.) and with/without index.html, causing Google to flag them as duplicates without user-selected canonical URLs.

Created scripts/add-canonical-tags.js that automatically injects canonical tags during the documentation generation process. The script properly handles index.html files, converts relative canonical URLs to absolute, and is integrated into the Makefile generate target to run after TypeDoc/JavaDoc generation.

All generated HTML files now include proper canonical tags pointing to clean, absolute URLs.

[asafashirov]

will not do

[claude]

Review Summary

This PR successfully addresses the Google Search Console duplicate content warnings by adding canonical link tags to 1,621 static HTML files in the API reference documentation. The implementation is clean, well-structured, and follows best practices.

✅ Approved Items

Script Implementation (scripts/add-canonical-tags.js)

• Correctly generates absolute canonical URLs with proper base URL (https://www.pulumi.com)
• Properly handles index.html files by stripping them from canonical paths (e.g., /path/index.html → /path/)
• Includes appropriate safeguards: checks for existing canonical tags, handles missing head closing tags gracefully
• Good error handling with try-catch blocks
• File ends with newline as required ✓
• Uses existing glob dependency from package.json ✓

Makefile Integration (line 52)

• Correctly integrated into the generate target after documentation generation
• Runs at the appropriate time (after TypeDoc/JavaDoc generation)
• Includes helpful echo message for visibility

HTML File Changes

• All 1,621 files verified to have canonical tags properly placed before head closing tag
• URLs are correctly formatted (e.g., https://www.pulumi.com/docs/reference/pkg/dotnet/Pulumi.Automation/Pulumi.Automation.ConfigValue.html)
• Canonical tags follow proper HTML5 syntax with self-closing format

SEO Benefits

• Resolves duplicate content issues caused by query parameters (?iaid, ?__hstc, etc.)
• Eliminates index.html variants being indexed separately
• Provides clear signals to search engines about the canonical version of each page

📝 Minor Observations (No Action Required)

1. Script placement in Makefile: The script runs in the generate target, meaning it will re-process all HTML files every time make generate is run. The script does handle this efficiently by checking for existing canonical tags and skipping files with correct tags already present.

2. Console output: The script provides detailed logging which is helpful for debugging but may be verbose during regular builds. This is acceptable for a maintenance script.

3. Path handling: Uses forward slashes which works correctly on Linux/macOS. The replace on line 14 ensures Windows paths are normalized, though this repository likely runs on Unix-like systems.

✅ Repository Guidelines Compliance

• ✓ File ends with newline (verified)
• ✓ No code comments unless needed (clean, self-documenting code)
• ✓ Uses existing dependencies (glob from package.json)
• ✓ Integrated into Makefile as specified in AGENTS.md
• ✓ Proper SEO implementation addressing canonical URLs

🎯 Conclusion

This PR effectively solves the duplicate content issue and is ready to merge. The solution is maintainable, follows repository conventions, and will automatically keep canonical tags updated when documentation is regenerated.

---

Mention @claude if you need additional reviews or want me to analyze specific aspects in more detail!

[pulumi-bot]

Your site preview for commit 0a4b95a is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16398-0a4b95a8.s3-website.us-west-2.amazonaws.com.