feat(doc-kit): bump version, use virtualImports by avivkeller · Pull Request #29 · nodejs/learn

avivkeller · 2026-04-04T17:56:04Z

Updates doc-kit to the latest version, adding support for:

Custom canonical links (<link rel="canonical" href="https://nodejs.org/learn{path}" />) (cc @MattIPv4)
Loading navigation and sidebar from file via virtualImports (cc @ovflowd)

vercel · 2026-04-04T17:56:06Z

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

Project	Deployment	Actions	Updated (UTC)
nodejs-learn	Ready	Preview	Apr 4, 2026 6:41pm

Copilot

Pull request overview

Updates the Learn site’s doc-kit setup to the latest version and shifts navigation/canonical behavior to be driven by a shared template and virtual JSON imports, aligning Learn with nodejs.org site navigation data.

Changes:

Bump @node-core/doc-kit to 1.3.2 and configure templatePath + canonical link rendering.
Introduce build-time virtualImports for #site/navigation.json (from nodejs.org) and #learn/navigation.json (derived from local navigation.json + page titles).
Refactor Sidebar/Nav/Footer components to consume the virtual navigation JSON instead of hardcoded/static local data.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
utils/index.mjs	Adds helpers to derive sidebar groupings + i18n population used by virtual imports.
template.html	New HTML template including canonical link and updated head tags.
package.json	Bumps doc-kit devDependency to 1.3.2.
package-lock.json	Lockfile update for doc-kit 1.3.2.
navigation.json	Adds local Learn sidebar grouping source (paths per category).
doc-kit.config.mjs	Configures template and adds `virtualImports` for site + learn navigation.
components/Sidebar/index.jsx	Switches sidebar groups to `#learn/navigation.json` virtual import.
components/Navigation/index.jsx	Switches top nav items to `#site/navigation.json` virtual import.
components/Footer/index.jsx	Switches footer links/social links to `#site/navigation.json` virtual import.
components/Footer/footer.json	Removes now-redundant local footer navigation JSON.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

utils/index.mjs

doc-kit.config.mjs

ovflowd

Left a few comments.

ovflowd · 2026-04-04T17:59:38Z

doc-kit.config.mjs

+      '#site/navigation.json': JSON.stringify(
+        populateI18n(
+          await fetch(
+            'https://raw.githubusercontent.com/nodejs/nodejs.org/refs/heads/main/apps/site/navigation.json'


Could this pretty please be a constant?

Why we adding a navigation.json ref? When we also adding a navigation.json file?

#site/navigation is for the navbar and footer
#learn/navigation is for the sidebar

Constant please and inline doc explaining the diff

template.html

ovflowd · 2026-04-04T18:01:32Z

utils/index.mjs

+    ),
+  }));
+
+export const createI18nPopulator = async () => {


No, let's not mess with anything i18n here, completely out of scope, please.

We are fetching the site navigation from https://github.com/nodejs/nodejs.org/blob/main/apps/site/navigation.json, which needs i18n resolved.

Hard no for this, we shouldn't use the navigation from there NOR use i18n here. These are separate projects, let's not link them. If we ever need to update the Navigation there, we can just open a PR updating it here too.

Let's please remove this dependency.

ovflowd · 2026-04-04T18:02:14Z

utils/index.mjs

+
+export const PAGES_DIR = join(import.meta.dirname, '../pages');
+
+export const getTitle = async path => {


Rather than specifying the title both in the page and the config, we can just get it from the page, no?

Let's please not. Let's follow what we've been doing already, manually specifying the title, this is supposed to be as static and manual as possible, let's not add automatic magic things.

On nodejs/node sidebar titles !== content title, same on Node.js org, so let's also manually define them here 🙇

MattIPv4

👀 https://nodejs-learn-git-doc-kit-improvements-openjs.vercel.app/learn/ has a canonical of <link rel="canonical" href="https://nodejs.org/learn/index">, that isn't right.

avivkeller · 2026-04-04T18:37:02Z

Okay, I need to fix doc-kit to strip the /index, reverting that change. I'm also going to add a useAbsoluteURLs config to doc-kit which will resolve all of our relative URLs hacks.

In the meantime, fixed Vercel config for more relative URL issues

Signed-off-by: Aviv Keller <me@aviv.sh>

avivkeller · 2026-04-04T19:28:24Z

See: nodejs/doc-kit#751

MattIPv4 · 2026-04-04T19:29:53Z

vercel.json

Why are these pages special? Not sure I'm a fan of having complex redirect rules like this?

Nor am I, we can remove them after nodejs/doc-kit#751. These pages are all /index.html, and need the forward slash until we stop using relative URLs in 751.

Why are they /index.html pages though? Why aren't they being generated as <path>.html like all our other pages?

Absolute URL support fixes this, sure, but doesn't actually address why these are being generated differently from all the other pages?

They aren't generated differently, they are written as index.md pages in the source content, for instance https://github.com/nodejs/learn/blob/main/pages/diagnostics/memory/index.md

That seems like something doc-kit should be able to handle then, and update its imports based on the fact that it knows it has generated an index instead of a path?

feat(doc-kit): bump version, use virtualImports

c79301c

Copilot AI review requested due to automatic review settings April 4, 2026 17:56

vercel bot deployed to Preview April 4, 2026 17:56 View deployment

Copilot started reviewing on behalf of avivkeller April 4, 2026 17:56 View session

fixup!

dfdbd6f

vercel bot deployed to Preview April 4, 2026 17:59 View deployment

Copilot AI reviewed Apr 4, 2026

View reviewed changes

utils/index.mjs Show resolved Hide resolved

utils/index.mjs Show resolved Hide resolved

utils/index.mjs Show resolved Hide resolved

doc-kit.config.mjs Show resolved Hide resolved

ovflowd reviewed Apr 4, 2026

View reviewed changes

MattIPv4 requested changes Apr 4, 2026

View reviewed changes

fixup! revert template changes, fix vercel

dcc2661

vercel bot deployed to Preview April 4, 2026 18:37 View deployment

Refactor routing rules in vercel.json

c62b2f2

Signed-off-by: Aviv Keller <me@aviv.sh>

vercel bot deployed to Preview April 4, 2026 18:41 View deployment

avivkeller mentioned this pull request Apr 4, 2026

feat(web): allow JS in template, absolute URL support nodejs/doc-kit#751

Open

MattIPv4 reviewed Apr 4, 2026

View reviewed changes


		export const PAGES_DIR = join(import.meta.dirname, '../pages');

		export const getTitle = async path => {

Conversation

avivkeller commented Apr 4, 2026

Uh oh!

vercel bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MattIPv4 left a comment

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Apr 4, 2026

Uh oh!

avivkeller commented Apr 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MattIPv4 Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Apr 4, 2026 •

edited

Loading

MattIPv4 Apr 4, 2026 •

edited

Loading