feat(scripts): set up by avivkeller · Pull Request #2 · nodejs/learn

avivkeller · 2026-03-25T17:15:35Z

Adds some logic to get this basically set up. cc @nodejs/web-admins for deployment previews

Copilot

Pull request overview

Sets up the repository’s initial build/tooling for generating a Doc Kit static site, including a prebuild step that generates a shared navigation/authors config consumed by custom theme components.

Changes:

Add a config-generation script (prebuild) that fetches nav/i18n/authors and derives sidebar + page author mappings from pages/.
Add Doc Kit configuration plus custom theme components (Navigation/Sidebar/Metabar) wired via #theme/* imports.
Add baseline repo tooling/docs: package.json scripts/deps, ESLint flat config, README/CONTRIBUTING.

Reviewed changes

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

Show a summary per file

File	Description
scripts/generate-config.mjs	Generates `components/config.json` from remote JSON + local `pages/` content.
scripts/constants.mjs	Centralizes paths and remote source URLs used by the generator.
package.json	Defines build/lint/format scripts and dependencies (including `prebuild`).
eslint.config.mjs	Adds ESLint flat config with TypeScript + MDX support.
doc-kit.config.mjs	Configures Doc Kit generators and maps `#theme/*` to local components.
components/Sidebar/index.jsx	Sidebar component consuming generated `sideNav`.
components/Navigation/index.jsx	Top navigation/search/theme toggle consuming generated `topNav`.
components/Metabar/index.jsx	Metabar/TOC + “Authors” + “Edit this page” consuming generated `authors`.
README.md	Documents repo purpose and local build workflow.
CONTRIBUTING.md	Documents content structure and contribution workflow.

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

scripts/generate-config.mjs

scripts/constants.mjs

package.json

components/Metabar/index.jsx

scripts/generate-config.mjs

eslint.config.mjs

ovflowd · 2026-03-27T19:18:32Z

components/Metabar/index.jsx

+      headings={{ items: headings }}
+      items={{
+        'Reading Time': readingTime,
+        ...(CLIENT && pageAuthors?.length


Can... we extract this to a const, to avoid doing this ternary right here?

ovflowd · 2026-03-27T19:18:57Z

scripts/constants.mjs

+import { join } from 'node:path';
+
+// Inputs & Outputs
+export const PAGES_DIR = join(import.meta.dirname, '..', 'pages');


nit: Can we separate constants by a new line?

ovflowd · 2026-03-27T19:19:48Z

scripts/generate-config.mjs

Is this generating the doc-kit config? Can then you rename as generate-doc-kit-config.mjs?

And can you move all the utils to like scripts/utils/[..] to make the entrypoint cleaner?

Is this generating the doc-kit config?

Not quite. It's generating a configuration to be used by the UI components, since we don't currently pass additional frontmatter to custom layouts. The doc-kit config is seperate, but I can make it clearer

ovflowd

SGTM! Left tiny comments and the PR title should probably match that it adds the scripts and initial packages and components :)

canerakdas · 2026-03-28T12:05:07Z

scripts/generate-config.mjs

+ * @property {string}   group     - Top-level directory slug (first path segment).
+ * @property {string}   pathname  - URL pathname derived from the file path.
+ * @property {string}   label     - Page title extracted from the first H1.


For JSDoc, I think we should leave just a single space between parameter names and their descriptions. In some places they're aligned, in others they're not instead of adding extra spaces to force alignment, it's better to keep them as-is

canerakdas · 2026-03-28T12:09:57Z

scripts/generate-config.mjs

+ * @property {string}   group     - Top-level directory slug (first path segment).
+ * @property {string}   pathname  - URL pathname derived from the file path.
+ * @property {string}   label     - Page title extracted from the first H1.
+ * @property {string[]} authorIds - GitHub usernames listed in the YAML front-matter.


I think using Array<string> instead of string[] makes the code more readable. It would be nice to keep the same standards we use in website here as well

canerakdas · 2026-03-28T12:31:17Z

scripts/generate-config.mjs

+ * @returns {string[]} An array of trimmed, non-empty author IDs.
+ */
+const extractAuthorIds = content => {
+  const yaml = content.match(/<!--\s*YAML\s+([\s\S]*?)-->/)?.[1] ?? '';


II think it would be better to define the regexes either in constants.mjs or at the top of the file and reference them from there. That way, we can manage changes from a single place and make the code easier to read

canerakdas · 2026-03-28T12:32:50Z

scripts/generate-config.mjs

+ * @returns {string[]} Ordered, deduplicated group slugs.
+ */
+const extractGroupOrder = content => [
+  ...new Set([...content.matchAll(/\]\(\/([\w-]+)\//g)].map(m => m[1])),


Suggested change

...new Set([...content.matchAll(/\]\(\/([\w-]+)\//g)].map(m => m[1])),

...new Set([...content.matchAll(/\]\(\/([\w-]+)\//g)].map(match => match[1])),

canerakdas · 2026-03-28T12:41:04Z

scripts/generate-config.mjs

+  const line = yaml.match(/^authors:\s*(.+)$/m)?.[1] ?? '';
+  return line
+    .split(',')
+    .map(s => s.trim())


Suggested change

.map(s => s.trim())

.map(authorId => authorId.trim())

Since we wouldn't be trimming anything other than a s/string anyway, we should use more meaningful variable names

canerakdas · 2026-03-28T12:59:29Z

scripts/generate-config.mjs

+ * @param {string} file - Relative file path (e.g. `"guides/intro.md"`).
+ * @returns {string} URL pathname (e.g. `"/guides/intro"`).
+ */
+const toPathname = file => '/' + file.replace(sep, '/').replace(/\.mdx?$/, '');


There are also cases where there isn't just a single /, and it could be made more readable something like;

Suggested change

const toPathname = file => '/' + file.replace(sep, '/').replace(/\.mdx?$/, '');

const toPathname = file => {

const path = file.split(sep).join('/');

const withoutExtension = path.replace(MARKDOWN_EXTENSION, '');

return '/' + withoutExtension;

};

diagnostics/poor-performance/using-linux-perf.md

canerakdas · 2026-03-28T13:04:45Z

scripts/generate-config.mjs

+
+  const sideNav = sortedEntries.map(([key, items]) => ({
+    groupName: slugToTitle(key),
+    items: items.map(p => ({ label: p.label, link: p.pathname + '.html' })),


Suggested change

items: items.map(p => ({ label: p.label, link: p.pathname + '.html' })),

items: items.map(({ label, pathname }) => ({ label, link: pathname + '.html' })),

Lets destructure to make the properties self-documenting

canerakdas · 2026-03-28T13:05:39Z

scripts/generate-config.mjs

+
+  const authors = Object.fromEntries(
+    pages
+      .filter(p => p.authorIds.length > 0)


Suggested change

.filter(p => p.authorIds.length > 0)

.filter(({authorIds}) => authorIds.length > 0)

canerakdas · 2026-03-28T13:06:24Z

scripts/generate-config.mjs

+      .map(p => [
+        toEditUrl(p.pathname),
+        p.authorIds.map(id => resolveAuthor(id, authorsById)),
+      ])


Suggested change

.map(p => [

toEditUrl(p.pathname),

p.authorIds.map(id => resolveAuthor(id, authorsById)),

])

.map(({pathname, authorIds}) => [

toEditUrl(pathname),

authorIds.map(id => resolveAuthor(id, authorsById)),

])

canerakdas · 2026-03-28T13:13:07Z

scripts/generate-config.mjs

+ * Reads every markdown page under {@link PAGES_DIR} and produces the sidebar
+ * navigation groups and a per-page authors mapping.
+ * @param {Map<string, AuthorEntry>} authorsById - Lookup map of known authors.
+ * @returns {Promise<{ sideNav: SideNavGroup[], authors: Record<string, ResolvedAuthor[]> }>}


Should we define this as a typedef as well? Honestly, it looks a bit complex here 🤔

canerakdas · 2026-03-28T13:19:30Z

adding .editorconfig would be great before merging any script 🙏

Ref: https://github.com/nodejs/doc-kit/blob/main/.editorconfig

canerakdas · 2026-03-28T13:26:46Z

scripts/generate-config.mjs

+/**
+ * @typedef {Object} BuildOutput
+ * @property {NavItem[]}      topNav  - Top-level navigation items.
+ * @property {SideNavGroup[]} sideNav - Grouped sidebar navigation.
+ * @property {Record<string, ResolvedAuthor[]>} authors - Authors keyed by edit URL.
+ */


This typedef is not being used 👀

canerakdas · 2026-03-28T13:30:33Z

package.json

+    "eslint": "^10.1.0",
+    "eslint-plugin-mdx": "^3.7.0",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",


If we're not going to add the pre-commit hook, we should remove the husky dependency

canerakdas · 2026-03-28T13:45:47Z

Also I think we should create learn version of these configs;

feat(scripts): set up

74b07b5

Copilot AI review requested due to automatic review settings March 25, 2026 17:15

Copilot started reviewing on behalf of avivkeller March 25, 2026 17:16 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

avivkeller requested a review from a team March 25, 2026 20:59

ovflowd reviewed Mar 27, 2026

View reviewed changes

ovflowd approved these changes Mar 27, 2026

View reviewed changes

canerakdas reviewed Mar 28, 2026

View reviewed changes

	...new Set([...content.matchAll(/\]\(\/([\w-]+)\//g)].map(m => m[1])),
	...new Set([...content.matchAll(/\]\(\/([\w-]+)\//g)].map(match => match[1])),

-const toPathname = file => '/' + file.replace(sep, '/').replace(/\.mdx?$/, '');
+const toPathname = file => {
+  const path = file.split(sep).join('/');
+  const withoutExtension = path.replace(MARKDOWN_EXTENSION, '');
+  return '/' + withoutExtension;
+};

	items: items.map(p => ({ label: p.label, link: p.pathname + '.html' })),
	items: items.map(({ label, pathname }) => ({ label, link: pathname + '.html' })),

	.filter(p => p.authorIds.length > 0)
	.filter(({authorIds}) => authorIds.length > 0)

Conversation

avivkeller commented Mar 25, 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!

Uh oh!

Uh oh!

Uh oh!

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!

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!

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!

canerakdas commented Mar 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

canerakdas commented Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

avivkeller commented Mar 25, 2026 •

edited

Loading