feat: restore previous and next article navigation

[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 1, 2026 12:02am 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.