feat(scripts): set up

Author: avivkeller

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to nodejs/learn
+
+Thank you for your interest in contributing! This repository contains the
+Node.js learning guides published at [learn.nodejs.org](https://learn.nodejs.org).
+
+## Content structure
+
+All articles live under `pages/`, organized into topic sections:
+
+| Directory             | Topics covered                                          |
+| --------------------- | ------------------------------------------------------- |
+| `getting-started/`    | Introduction, V8 engine, dev vs production, WebAssembly |
+| `asynchronous-work/`  | Event loop, callbacks, promises, streams                |
+| `command-line/`       | REPL, environment variables, CLI I/O                    |
+| `diagnostics/`        | Debugging, profiling, memory, performance               |
+| `file-system/`        | File paths, stats, reading, writing, folders            |
+| `http/`               | HTTP transactions, fetch, WebSockets, proxies           |
+| `package-management/` | npm, publishing packages, Node-API modules              |
+| `security/`           | Security best practices                                 |
+| `testing/`            | Test runner, mocking, code coverage                     |
+| `typescript/`         | TypeScript with Node.js                                 |
+
+## Making changes
+
+### Editing an existing article
+
+1. Find the relevant `.md` file under `pages/`.
+2. Edit the content (standard GitHub-flavored Markdown).
+3. Open a pull request — no build step required to review prose changes.
+
+### Adding a new article
+
+1. Choose the most relevant section directory, or propose a new one in your PR.
+2. Create a new `.md` file with a descriptive kebab-case name.
+3. Include frontmatter at the top of the file if required by `doc-kit`.
+
+### Adding a new section
+
+Open an issue first to discuss the proposed section before adding files.
+Refer to the [Card Sort results](https://github.com/nodejs/nodejs.org/issues/8234)
+for prior user-research context on content organisation.
+
+## Building locally
+
+```bash
+npm install
+npm run build
+# Output is written to out/
+```
+
+## Code of Conduct
+
+This project follows the
+[Node.js Code of Conduct](https://github.com/nodejs/admin/blob/main/CODE_OF_CONDUCT.md).

README.md

@@ -0,0 +1,43 @@
+# nodejs/learn
+
+Source content for the Node.js learning guides, published at
+[learn.nodejs.org](https://learn.nodejs.org).
+
+This repository was created as part of
+[nodejs/nodejs.org#8612](https://github.com/nodejs/nodejs.org/issues/8612)
+to give the Learn content a dedicated home, separate from the main website
+monorepo. Content editors no longer need to deal with Next.js tooling or
+website-specific git hooks.
+
+## Content
+
+All articles are Markdown files under `pages/`, grouped by topic:
+
+```
+pages/
+├── getting-started/        # Introduction to Node.js
+├── asynchronous-work/      # Event loop, callbacks, promises, streams
+├── command-line/           # REPL, environment variables, CLI I/O
+├── diagnostics/            # Debugging, profiling, memory, performance
+├── file-system/            # File paths, stats, reading/writing, folders
+├── http/                   # HTTP, fetch, WebSockets, proxies
+├── package-management/     # npm, publishing packages, Node-API modules
+├── security/               # Security best practices
+├── testing/                # Test runner, mocking, code coverage
+└── typescript/             # TypeScript with Node.js
+```
+
+The structure is based on
+[Card Sort research](https://github.com/nodejs/nodejs.org/issues/8234)
+conducted at the 2025 Cambridge Node.js Collaborators' Summit.
+
+## Development
+
+```bash
+npm install
+npm run build   # generates static site + Orama search DB in out/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

components/Metabar/index.jsx

@@ -0,0 +1,41 @@
+import MetaBar from '@node-core/ui-components/Containers/MetaBar';
+import AvatarGroup from '@node-core/ui-components/Common/AvatarGroup';
+import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
+
+import { authors } from '../config.json' with { type: 'json' };
+
+/**
+ * @typedef MetaBarProps
+ * @property {Array<import('@vcarl/remark-headings').Heading>} headings
+ * @property {string} readingTime
+ * @property {Array<[string, string]>} viewAs
+ * @property {string} editThisPage
+ */
+
+/** @param {MetaBarProps} props */
+export default ({ headings = [], readingTime, viewAs = [], editThisPage }) => {
+  const pageAuthors = authors[editThisPage];
+
+  return (
+    <MetaBar
+      heading="Table of Contents"
+      headings={{ items: headings }}
+      items={{
+        'Reading Time': readingTime,
+        ...(CLIENT && pageAuthors?.length
+          ? {
+              Authors: (
+                <AvatarGroup avatars={pageAuthors} as="a" clickable limit={5} />
+              ),
+            }
+          : {}),
+        Contribute: (
+          <>
+            <GitHubIcon className="fill-neutral-700 dark:fill-neutral-100" />
+            <a href={editThisPage}>Edit this page</a>
+          </>
+        ),
+      }}
+    />
+  );
+};

components/Navigation/index.jsx

@@ -0,0 +1,37 @@
+import ThemeToggle from '@node-core/ui-components/Common/ThemeToggle';
+import NavBar from '@node-core/ui-components/Containers/NavBar';
+import styles from '@node-core/ui-components/Containers/NavBar/index.module.css';
+import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
+
+import SearchBox from '@node-core/doc-kit/src/generators/web/ui/components/SearchBox';
+import { useTheme } from '@node-core/doc-kit/src/generators/web/ui/hooks/useTheme.mjs';
+
+import Logo from '#theme/Logo';
+import { topNav } from '../config.json' with { type: 'json' };
+
+/**
+ * NavBar component that displays the headings, search, etc.
+ */
+export default () => {
+  const [theme, toggleTheme] = useTheme();
+
+  return (
+    <NavBar
+      Logo={Logo}
+      sidebarItemTogglerAriaLabel="Toggle navigation menu"
+      navItems={topNav}
+    >
+      <SearchBox />
+      <ThemeToggle
+        onClick={toggleTheme}
+        aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} theme`}
+      />
+      <a
+        href={`https://github.com/nodejs/learn`}
+        className={styles.ghIconWrapper}
+      >
+        <GitHubIcon />
+      </a>
+    </NavBar>
+  );
+};

components/Sidebar/index.jsx

@@ -0,0 +1,23 @@
+import SideBar from '@node-core/ui-components/Containers/Sidebar';
+
+import { sideNav } from '../config.json' with { type: 'json' };
+
+/**
+ * Redirect to a URL
+ * @param {string} url URL
+ */
+const redirect = url => (window.location.href = url);
+
+/**
+ * Sidebar component for MDX documentation with page navigation
+ * @param {{ pathname: string }} props
+ */
+export default ({ pathname }) => (
+  <SideBar
+    pathname={pathname}
+    groups={sideNav}
+    onSelect={redirect}
+    as={props => <a {...props} rel="prefetch" />}
+    title="Navigation"
+  />
+);

doc-kit.config.mjs

@@ -0,0 +1,32 @@
+import web from '@node-core/doc-kit/src/generators/web/index.mjs';
+import { join } from 'node:path';
+
+/** @type {import('@node-core/doc-kit/src/utils/configuration/types.d.ts').Configuration} */
+export default {
+  global: {
+    output: 'out',
+    input: ['pages/**/*.md'],
+  },
+  'jsx-ast': {
+    pageURL: 'https://learn.nodejs.org{path}.html',
+    editURL: 'https://github.com/nodejs/learn/edit/main/pages{path}.md',
+  },
+  web: {
+    title: '',
+    imports: {
+      ...web.defaultConfiguration.imports,
+      '#theme/Navigation': join(
+        import.meta.dirname,
+        'components/Navigation/index.jsx'
+      ),
+      '#theme/Sidebar': join(
+        import.meta.dirname,
+        'components/Sidebar/index.jsx'
+      ),
+      '#theme/Metabar': join(
+        import.meta.dirname,
+        'components/Metabar/index.jsx'
+      ),
+    },
+  },
+};

eslint.config.mjs

@@ -0,0 +1,31 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+import { defineConfig } from 'eslint/config';
+import * as mdx from 'eslint-plugin-mdx';
+
+export default defineConfig(
+  { ignores: ['out'] },
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  mdx.flatCodeBlocks,
+  {
+    languageOptions: {
+      globals: globals.nodeBuiltin,
+    },
+  },
+  {
+    files: ['**/*.{md,mdx}/*.cjs'],
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+  },
+  {
+    ...mdx.flat,
+    processor: mdx.createRemarkProcessor({ lintCodeBlocks: true }),
+    rules: {
+      ...mdx.flat.rules,
+      'no-irregular-whitespace': 'off',
+    },
+  }
+);