Proposal: Move Learn content to a dedicated `nodejs/learn` repository

[ovflowd]

Summary

Following discussion in the Website Team Slack (thread 1, thread 2, thread 3), we've reached consensus on splitting the Learn content out of this repository into a dedicated nodejs/learn repository, published at learn.nodejs.org.

This addresses several long-standing concerns:

• Repository complexity: The current monorepo bundles content (Markdown) with the Next.js application, adding unnecessary friction for content contributors who don't need the full site development setup.
• Content ownership: Learn content is often maintained by different teams/WGs than the website application itself. A separate repo makes ownership boundaries clearer.
• DX for content-only contributors: Contributors editing Markdown guides shouldn't need to deal with the site's tooling, dependencies, or git hooks (related discussion context).
• Content quality & structure: The learn content needs significant restructuring (see Card Sort Session Results from the 2025 Collaborators Summit). An isolated repo makes this easier to manage.

Plan

The work would be broken into the following phases:

Phase 1: Prepare doc-kit for general-purpose use

• Finish getting @nodejs/doc-kit ready to generate content beyond Node.js API docs (see doc-kit 2026 Roadmap)
• Ensure the web generator and configuration file support allows doc-kit to power a standalone Learn site

Phase 2: Create nodejs/learn repository

• Create the nodejs/learn repository
• Set up the project structure using doc-kit for page generation
• Copy the Learn pages (Markdown content) from this repository
• Ensure good CI/CD pipeline (linting, build, preview deployments)
• Ensure good DX (clear contribution guidelines, simple setup for content contributors)
• Write documentation for contributing, local development, and content guidelines

Phase 3: Deploy and publish

• Deploy to Vercel
• Configure learn.nodejs.org via Cloudflare DNS
• Ensure search functionality works (Orama or equivalent)
• Ensure SEO is preserved (proper metadata, canonical URLs, sitemaps)

Phase 4: Redirect and clean up

• Update nodejs.org to redirect /learn/* routes to learn.nodejs.org
• Remove Learn content from this repository
• Update any cross-references, links, and documentation

Phase 5 (Follow-up): Expand content scope

• Potentially move addon examples, other guides, and educational content to nodejs/learn
• Restructure content in a practical manner (informed by Card Sort results)

Context

Relevant Slack threads where consensus was reached:

• https://openjs-foundation.slack.com/archives/CVAMEJ4UV/p1770210366603769
• https://openjs-foundation.slack.com/archives/CVAMEJ4UV/p1770210649196749
• https://openjs-foundation.slack.com/archives/CVAMEJ4UV/p1769124848274889

Key points from the discussion:

• The Website Team is not in favor of splitting web components into a separate repo (that would degrade DX for the web team).
• The team is in favor of splitting Learn content, as it's an isolated set of Markdown files that benefits from a simpler, dedicated repository.
• doc-kit is already on the roadmap to become a general-purpose documentation toolkit (doc-kit#594), making it the natural choice for powering the Learn site.

/cc @nodejs/nodejs-website

[avivkeller]

Finish getting @nodejs/doc-kit ready to generate content beyond Node.js API docs (see nodejs/doc-kit#594)

See nodejs/doc-kit#593 for the addition of a configuration file. Once that's done, we can add more configs for more fine-tuning