[dcavalcante]

Description

Restores previous and next article navigation at the bottom of Learn articles.

On smaller screens, the sidebar is replaced by a navigation dropdown near the top of the page. After reading a long article, continuing to the next article currently requires scrolling back to the top. This adds the same sequential navigation at the end of the article.

The links reuse the existing BaseCrossLink component and follow the same article order as the sidebar navigation.

Background

Previous/next navigation has existed in earlier versions of the Learn experience.

nodejs/doc-kit#928 identified the absence of previous/next links on Node.js Learn after the doc-kit migration as a regression.

Support was subsequently added to doc-kit in nodejs/doc-kit#1012, which introduced opt-in cross-links through navigation.showCrossLinks.

Learn currently overrides doc-kit's default #theme/Layout, so the cross-link rendering provided by doc-kit's default layout is not used.

There is also earlier history for Learn-specific previous/next navigation:

nodejs/nodejs.org#5242 discussed migrating the old pagination component as a Learn-specific PreviousNextLink.

nodejs/nodejs.org#5331 implemented that component.

nodejs/nodejs.org#5705 removed it temporarily while the new website design was being introduced.

nodejs/nodejs.org#5761 and nodejs/nodejs.org#5781 introduced the redesigned CrossLink component that this change now reuses.

Implementation

• Adds an ArticleNavigation component beneath article content.
• Reuses BaseCrossLink for the existing Previous/Next design.
• Uses site.json as the navigation source of truth.
• Recursively flattens nested sidebar sections to their leaf articles, matching the ordering used by the mobile navigation dropdown.
• Continues navigation across sidebar groups.
• Keeps Previous and Next links side-by-side on larger screens.
• Stacks them vertically on smaller screens.
• Hides the desktop alignment placeholder on mobile when only a Next link is present.

The recursive flattening is intentional because Learn contains nested sidebar sections such as Diagnostics and Node-API.

Validation

Added Playwright coverage for:

• previous and next links on an article in the middle of a section
• navigation across sidebar group boundaries
• nested sidebar sections
• first-article behavior
• mobile navigation from the bottom of an article

Locally verified with:

npm run lint
npm run format:check
npm run build
npm run test:e2e

All 20 end-to-end tests pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nodejs-learn	Ready	Preview	Oct 31, 2026 10:15pm UTC

[github-actions]

👋 Codeowner Review Request

The following codeowners have been identified for the changed files:

Team reviewers: @nodejs/nodejs-website

Please review the changes when you have a chance. Thank you! 🙏

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation matches sidebar leaf ordering and includes comprehensive end-to-end coverage.

Review effort: Balanced
Findings: None

What changed in this PR

Restores previous/next navigation beneath Learn articles using sidebar ordering.

Changes:

• Adds recursive article ordering and cross-links.
• Supports responsive layouts and mobile placeholders.
• Adds end-to-end navigation coverage.

File	Description
components/​ArticleNavigation/​index.jsx	Implements article cross-links.
components/​ArticleNavigation/​index.module.css	Adds responsive styling.
components/​Layout/​index.jsx	Renders navigation below article content.
tests/​e2e/​interactions.spec.mjs	Tests ordering, boundaries, nesting, and mobile navigation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ovflowd]

@dcavalcante apologies for the delay here to review it. Out of curiosity, what happens if we don't use this custom layout? Is there a reason we should keep using it? (cc @avivkeller)

[ovflowd]

Anyways, SGTM

[dcavalcante]

@dcavalcante apologies for the delay here to review it. Out of curiosity, what happens if we don't use this custom layout? Is there a reason we should keep using it? (cc @avivkeller)

Yeah, I looked into that as well.. but removing the #theme/Layout override outright would currently change more than just the cross-links: the Learn layout mounts Analytics/Speed Insights and wires in the Learn-specific Navigation, Sidebar, Metabar (including authors), and legal Footer..

I think we could potentially move those components to the individual doc-kit theme slots and go back to the default Layout, which would also let us use navigation.showCrossLinks directly. Analytics would still need a home, though.. That seems like a worthwhile cleanup, but a somewhat broader refactor than restoring the missing navigation here.

[ovflowd]

I think we could potentially move those components to the individual doc-kit theme slots

Im unsure if prev/next links should be theme slots 🤔 (wdyt @avivkeller?)

[ovflowd]

Feel free to think of a long-term solution, @dcavalcante. I'll merge your PR for now. Appreciate your contribution!

[dcavalcante]

Thanks for merging @ovflowd!

Just to clarify, I wasn't suggesting making prev/next links separate theme slots. They're already handled by doc-kit's default Layout through navigation.showCrossLinks.. I meant moving Learn's existing Navigation, Sidebar, Metabar, and Footer customizations to their corresponding #theme/* overrides, so Learn could potentially use the default Layout.

There are a few compatibility details to work through first, particularly analytics, component props, and nested sidebar navigation. I'll investigate those separately and see whether there's a clean way to get there..