Skip to content

fix: skip rel=alternate markdown link on versioned docs pages#2283

Merged
barjin merged 3 commits intomasterfrom
copilot/fix-alternate-link-404-issue
Feb 25, 2026
Merged

fix: skip rel=alternate markdown link on versioned docs pages#2283
barjin merged 3 commits intomasterfrom
copilot/fix-alternate-link-404-issue

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Feb 25, 2026 •
edited by cursor Bot
Loading

  • Identify the issue: rel=alternate markdown links 404 on versioned pages
  • Use useAllDocsData from @docusaurus/plugin-content-docs/client to detect versioned pages without URL regex parsing
  • Skip rendering the <link rel="alternate"> when the current page is a versioned (non-latest) docs page
  • Apply linter autofix (npm run lint:fix) - resolved implicit-arrow-linebreak and max-len errors
Original prompt

This section details on the original issue you should resolve

<issue_title>rel=alternate markdown links lead to 404 for versioned pages</issue_title>
<issue_description>In some projects (e.g. apify-client-js), the common theme adds <link rel=alternate> elements with links to .md version of the resource.

This link will lead to a missing resource (server responds with 404) if the page is versioned (e.g., https://docs.apify.com/api/client/js/reference/next/interface/RequestQueueUserOptions).

See implementation:

apify-docs/apify-docs-theme/src/theme/Layout/index.jsx

Lines 13 to 25 in 9b625d7

const shouldRenderAlternateLink = currentPath && currentPath !== '404';
const alternateMarkdownLink = useBaseUrl(`/${currentPath}.md`, { absolute: true });
return (
<>
<Head>
{
shouldRenderAlternateLink
? <link rel="alternate" type="text/markdown" href={alternateMarkdownLink}/>
: null
}
</Head>
</issue_description>

<agent_instructions>provide a minimal fix for the described issue. do not render the link if the url is versioned (try using docusaurus hooks for it, try not parsing the URL with regex if you can). use conventional commits for the commit message and the PR title. do not add excessive comments.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Note

Low Risk
Small, UI-only head tag change gated by Docusaurus docs metadata; risk is limited to accidentally suppressing the alternate link on some pages.

Overview
Prevents broken rel="alternate" markdown links on versioned (non-latest) Docusaurus docs pages by detecting when the current pathname falls under a non-last docs version via useAllDocsData and skipping link rendering.

Also refactors the layout wrapper to use pathname from useLocation() directly and adjusts the inline predicate formatting to satisfy lint rules.

Written by Cursor Bugbot for commit 2285289. Configure here.

@barjin
fix: skip rel=alternate link for versioned docs pages
b0c37f3 
Co-authored-by: barjin <61918049+barjin@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix rel=alternate markdown links for versioned pages fix: skip rel=alternate markdown link on versioned docs pages Feb 25, 2026
Copilot AI requested a review from barjin February 25, 2026 10:36
@github-actions github-actions Bot added this to the 135th sprint - Tooling team milestone Feb 25, 2026
@github-actions github-actions Bot added the t-tooling Issues with this label are in the ownership of the tooling team. label Feb 25, 2026
@apify-service-account
Copy link
Copy Markdown

apify-service-account commented Feb 25, 2026

Preview for this PR was built for commit b0c37f3 and is ready at https://pr-2283.preview.docs.apify.com!

@barjin
Copy link
Copy Markdown
Member

barjin commented Feb 25, 2026

@copilot run the linter autofix (npm run lint:fix)

@barjin
fix: apply linter autofix to Layout component
2285289 
Co-authored-by: barjin <61918049+barjin@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Feb 25, 2026

@copilot run the linter autofix (npm run lint:fix)

Done in 2285289. Fixed implicit-arrow-linebreak and max-len lint errors by reformatting the isVersionedPage expression.

@barjin barjin marked this pull request as ready for review February 25, 2026 11:00
@apify-service-account
Copy link
Copy Markdown

apify-service-account commented Feb 25, 2026

Preview for this PR was built for commit 2285289 and is ready at https://pr-2283.preview.docs.apify.com!

@barjin barjin merged commit 05eb493 into master Feb 25, 2026
17 checks passed
@barjin barjin deleted the copilot/fix-alternate-link-404-issue branch February 25, 2026 11:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@katzino katzino katzino approved these changes

@birosrichard birosrichard birosrichard approved these changes

@barjin barjin Awaiting requested review from barjin

Assignees

@barjin barjin

Copilot code review Copilot

Labels

t-tooling Issues with this label are in the ownership of the tooling team.

Projects

None yet

Milestone

135th sprint - Tooling team

Development

Successfully merging this pull request may close these issues.

rel=alternate markdown links lead to 404 for versioned pages

5 participants

@apify-service-account @barjin @katzino @birosrichard