diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
deleted file mode 100644
index 3a00478db6656..0000000000000
--- a/COLLABORATOR_GUIDE.md
+++ /dev/null
@@ -1,681 +0,0 @@
-# Node.js Collaborator Guide
-
-- [Issues and Pull Requests](#issues-and-pull-requests)
-- [Accepting Modifications](#accepting-modifications)
- - [Involving the Website Team](#involving-the-website-team)
-- [Technologies used in the Website](#technologies-used-in-the-website)
-- [Code editing](#code-editing)
- - [Adding new pages](#adding-new-pages)
- - [Create the page content](#create-the-page-content)
- - [Translating pages](#translating-pages)
-- [Creating Components](#creating-react-components)
- - [Styling a Component](#styling-a-component)
- - [Best practices when creating a Component](#best-practices-when-creating-a-component)
- - [How a new Component should look like when freshly created](#how-a-new-component-should-look-like-when-freshly-created)
- - [Best practices for Component development in general](#best-practices-for-component-development-in-general)
-- [The new Downloads page](#the-new-downloads-page)
- - [Adding a Download Installation Method](#adding-a-download-installation-method)
- - [Adding a Download Package Manager](#adding-a-download-package-manager)
-- [Unit Tests and Storybooks](#unit-tests-and-storybooks)
- - [General Guidelines for Unit Tests](#general-guidelines-for-unit-tests)
- - [General Guidelines for Playwright E2E Tests](#general-guidelines-for-playwright-e2e-tests)
- - [General Guidelines for Storybooks](#general-guidelines-for-storybooks)
-- [Publishing Packages](#publishing-packages)
-- [Remarks on Technologies used](#remarks-on-technologies-used)
-- [Seeking additional clarification](#seeking-additional-clarification)
-
-This document contains information for Collaborators of the Node.js website project regarding maintaining the code, documentation, and issues.
-
-Collaborators should be familiar with the guidelines for new contributors in [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-## Issues and Pull Requests
-
-Courtesy should always be shown to individuals submitting issues and pull requests to the Node.js website project.
-
-Collaborators should feel free to take full responsibility for managing issues and pull requests they feel qualified to handle, as long as this is done while being mindful of these guidelines, the opinions of other Collaborators and guidance of the Website Group.
-
-Collaborators may **close** any issue or pull request they believe is not relevant to the future of the Node.js project.
-Where this is unclear, the issue should be left open for several days for additional discussion.
-Where this does not yield input from Node.js Collaborators or additional evidence that the issue has relevance, then the issue may be closed.
-Remember that issues can always be re-opened if necessary.
-
-> \[!IMPORTANT]\
-> We recommend Collaborators to avoid Updating/Rebasing PRs unnecessarily, since we use [GitHub Merge Queues](https://github.blog/2023-07-12-github-merge-queue-is-generally-available/)
-> to merge Pull Requests, which automatically rebases and runs CI-checks against the latest base branch.
-
-## Accepting Modifications
-
-All Node.js code and documentation modifications should be performed via GitHub pull requests.
-Only the Website Team can merge their work and should do so carefully.
-
-All pull requests must be reviewed and accepted by a Collaborator with sufficient expertise who can take full responsibility for the change.
-In the case of pull requests proposed by an existing Collaborator, an additional Collaborator is required for sign-off.
-
-Pull Requests can only be merged after all CI Checks have passed.
-As usual, CI Checks need to be manually triggered by adding a `github_actions:pull-request` label to the Pull Request.
-
-In some cases, it may be necessary to summon a qualified Collaborator to a pull request for review by @-mention.
-
-If you are unsure about the modification and are not prepared to take full responsibility for the change, defer to another Collaborator.
-
-We recommend collaborators follow the guidelines on the [Contributing Guide](./CONTRIBUTING.md#before-merging) for reviewing and merging Pull Requests.
-
-### Involving the Website Team
-
-Collaborators may opt to elevate pull requests or issues to the group for discussion by mentioning `@nodejs/nodejs-website`. This should be done where a pull request:
-
-- has a significant impact on the codebase,
-- is inherently controversial; or
-- has failed to reach a consensus amongst the Collaborators who are actively participating in the discussion.
-
-The Website group should be the final arbiter where needed.
-
-## Technologies used in the Website
-
-The Node.js Website is built upon [React][] and [Next.js][] respectively, the UI Rendering Engine and the Framework that builds the Website;
-
-The Website also uses several other Open Source libraries (not limited to) listed below:
-
-- Styling is done with [PostCSS][] and CSS Modules
-- [Tailwind][] is used as our CSS Framework and the Foundation of our Design System
-- [Hero Icons](https://heroicons.com/) is an SVG Icon Library used within our Codebase
-- [Radix UI][] is a collection of customizable UI components
-- [Shiki][] is a Syntax Highlighter used for our Codeboxes
- - The syntax highlighting is done within the processing of the Markdown files with the MDX compiler as a Rehype plugin.
-- [MDX][] and Markdown are used for structuring the Content of the Website
-- [`next-intl`][] is the i18n Library adopted within the Website
- - It provides an excellent integration with Next.js, But it also supports standalone support for i18n if it eventually migrates from Next.js to something else.
- - Supports React Server Components and Next.js Middlewares
-- We use [Rehype](https://github.com/rehypejs/rehype) and [Remark](https://github.com/remarkjs/remark) to extend MDX functionality
-- We use [Storybook](https://storybook.js.org/) for Manual Testing and Visual Regression Tests of our React Components
- - Storybook also provides a sandboxed environment, which is very useful whilst for crafting React Components
-
-## Code Editing
-
-### Structure of this Repository
-
-โ ๏ธ The repository is actively under migration to a multi-package workspace.
-Locations are subject to change. (If you are someone updating these paths,
-please document those changes here.)
-
-- React Components are defined on `apps/site/components` and `packages/ui-components`
-- React Templates are defined on `apps/site/layouts`
-- Global Stylesheets are declared on `packages/ui-components/styles`
- - Styles are done with [PostCSS][] and [Tailwind][]
-- Public files are stored on `apps/site/public`
- - Static Images, JavaScript files, and others are stored within `apps/site/public/static`
-- Internationalisation is done on `apps/site/i18n`
- - React Localisation Data is stored within `apps/site/i18n/locales`
- - We use the [ICU Message Syntax](https://formatjs.io/docs/core-concepts/icu-syntax/) for Translations
- - Configuration for Locales is done within `apps/site/i18n/config.json`
-- Website Content is defined within `apps/site/pages`
- - Initial development usually happens in English: `apps/site/pages/en`
- - Localized versions of `/pages/en` are done within `apps/site/pages/{localeCode}`
- - All content is in Markdown and is per locale.
- - The top of each Markdown file is a YAML (Frontmatter) block for page-specific localization information passed to various templates.
- - The bulk of the Markdown content for each page is referenced as `{children}` on their respective JSX Layout (`apps/site/layouts/`)
-- Multi-Purpose React Hooks are defined on `apps/site/hooks`
-- Multi-Purpose TypeScript definitions are defined on `apps/site/types`
-- React Context Providers are defined on `apps/site/providers`
-- Build-time Data Fetching Scripts are defined on `apps/site/next-data`
- - Used for Node.js Release data fetching
- - Generation of build-time indexes such as blog data
-- Multi-Purpose Scripts are stored within `apps/site/scripts`
- - Such as Node.js Release Blog Post generation
-- Storybook Configuration is done within `packages/ui-components/.storybook`
- - We use an almost out-of-the-box Storybook Experience with a few extra customisations
-
-### Adding new Pages
-
-1. Create new page content including the layout, title and copy.
-2. Update the relevant `apps/site/layout` to add a link to the new page.
-
-#### Create the page content
-
-Create a new markdown file in `apps/site/pages/en`.
-
-At the top of the markdown file, within the Markdown Frontmatter, set a page the title and layout.
-
-```markdown
----
-title: Title of the Page
-layout: layout-name
----
-
-[Content of the Page]
-```
-
-> \[!NOTE]\
-> A list of currently available Layouts is provided within `components/withLayout` on the `layoutComponents` map.\
-> This is a temporary map and this map might change its location and be defined in a different way in the future.
-
-### Translating Pages
-
-See the [Translation Guidelines](./TRANSLATION.md) for the website translation policy.
-
-## Creating React Components
-
-The Node.js Website uses [React][] as a Frontend Library to develop the Website.
-React allows us to create user interfaces with a modern take on Web Development.
-
-If you're unfamiliar with React or Web Development in general, we encourage a read before taking on complex issues and tasks as this repository is **not for educational purposes** and we expect you to have a basic understanding of the technologies used.
-
-We also recommend getting familiar with technologies such as [Next.js][], [MDX][], [PostCSS][], and "concepts" such as "CSS Modules" and "CSS-in-JS".
-
-### Styling a Component
-
-As mentioned, we write all Component-styles in separate `.module.css` files. This is like writing any CSS in a separate file (besides the fact that we use [PostCSS][]).
-
-This concept of writing styles on dedicated CSS files and importing them within JavaScript (or React) is a pattern named **[CSS Module](https://github.com/css-modules/css-modules)**.
-These allow us to write PostCSS (or regular CSS, or any flavor of CSS if you have a way of interpreting it) within a `.module.css` and import the class names directly to our React Components.
-We recommend reading guides on "Styling React Components with CSS Modules", which there are many available on the web.
-
-It's important to mention that we use [Tailwind][] as a CSS Framework. Hence, margins, paddings, font sizes, font weights, colors, and other sorts of styles are all provided with Tailwind.
-We recommend reading [Tailwind Docs](https://tailwindcss.com/docs/preflight) to get familiar with Tailwind's styles.
-We also recommend reading [this guide for setting up Tailwind on your IDE](https://tailwindcss.com/docs/editor-setup).
-
-Finally, if you're unfamiliar with how to use Tailwind or how to use Tailwind within CSS Modules, we recommend reading [this guide](https://tailwindcss.com/docs/using-with-preprocessors).
-
-#### Example of a CSS Module
-
-```css
-.myComponent {
- @apply some
- tailwind
- classes;
-}
-```
-
-#### Guidelines when writing CSS
-
-- We use camelCase for defining CSS classes
-- We use Tailwind's `@apply` selector to apply Tailwind utility classes
- - We discourage the usage of any plain CSS styles and tokens, when in doubt ask for help
- - We require that you define one Tailwind utility class per line, just as shown on the example above, since this improves readability
-- Only write CSS within CSS Modules, avoid writing CSS within JavaScript files
-
-> \[!NOTE]\
-> Tailwind is already configured for this repository. You don't need to import any Tailwind module within your CSS module.\
-> You can apply Tailwind utility classes with Tailwind's `@apply` CSS rule. [Read more about applying Tailwind utility classes with `@apply`](https://tailwindcss.com/docs/functions-and-directives#apply).
-
-> \[!IMPORTANT]\
-> When using IDEs such as Visual Studio Code, we recommend installing the official [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)
-> and [Tailwind](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) Extensions.\
-> These are recommended Extensions for IntelliSense, Syntax Highlighting and Error Checking when styling your Component.
-
-### Best practices when creating a Component
-
-- **All React components** should be placed within either `@node-core/ui-components` (for reusable components) or `apps/site/components` (for website-specific components).
-- **Generic UI components** that are not tied to the website should be placed in the `@node-core/ui-components` package.
- - These components should be **framework-agnostic** and must not rely on Next.js-specific features such as `usePathname()` or `useTranslations()`.
- - If a component previously relied on Next.js, it should now accept these values as **props** instead.
-- **Website-specific components** that rely on Next.js or are tied to the website should remain in `apps/site/components`.
- - These components can use Next.js-specific hooks, API calls, or configurations.
- - When using a generic UI component that requires Next.js functionality, pass it as a **prop** instead of modifying the component.
-- **Each component** should be placed within a sub-folder, which we call the **"Domain"** of the component.
- - The domain represents where the component belongs or where it will be used.
- - For example, components used within article pages or related to the structure of an article should be placed within `@node-core/ui-components/Common/Article`.
-- **Each component should have its own folder** with the name of the component.
-- The structure of each component folder follows this template:
-
- ```text
- - ComponentName
- - index.tsx // The component itself
- - index.module.css // Component-specific styles
- - index.stories.tsx // Storybook stories (only for @node-core/ui-components)
- - __tests__/ // Component tests (such as unit tests, etc.)
- - index.test.mjs // Unit tests should be done in ESM, not TypeScript
- ```
-
-- **If a component requires Next.js features, it should be wrapped within `apps/site`** rather than being modified directly in `@node-core/ui-components`.
-
- - Example: A component that requires `usePathname()` should **not** call it directly inside `@node-core/ui-components`. Instead:
- - The **base component** should accept `pathname` as a prop.
- - The **wrapper component** in `apps/site` should call `usePathname()` and pass it to the base component.
-
- Example structure:
-
- - **Base Component (`@node-core/ui-components`)**
-
- ```tsx
- const BaseComponent: FC<...> = ({ pathname, ariaLabel }) => {
- return <... ariaLabel={ariaLabel}>;
- };
- ```
-
- - **Wrapper Component (`apps/site/components`)**
-
- ```tsx
- const Component: FC<...> = (...) => {
- const pathname = usePathname();
- const t = useTranslations();
-
- return ;
- };
- ```
-
- - **Importing Components:**
- - **For website-specific functionality**, import the wrapper from `apps/site/components`.
- - **For direct UI use cases**, import from `@node-core/ui-components`.
-
-- **Storybook is now a dependency of `@node-core/ui-components`** and should not be included in `apps/site`.
-
- - Storybook stories should be written only for components in `@node-core/ui-components`.
-
-- **React Hooks that belong to a single component should be placed within that componentโs folder.**
-
- - If the hook has a **wider usability** or can be used by multiple components, it should be placed in the `apps/site/hooks` folder.
- - These hooks should only exist in `apps/site`.
-
-- **If a component has sub-components, they should follow the same structure as the main component.**
- - Example: If `ComponentName` has a sub-component called `SubComponentName`, it should be placed within:
- ```text
- - ComponentName/
- - index.tsx
- - SubComponentName/
- - index.tsx
- ```
-
-#### How a new Component should look like when freshly created
-
-```tsx
-import type { FC } from 'react';
-
-import styles from './index.module.css';
-
-type MyComponentProps = {}; // The types of the Props of your Component
-
-const MyComponent: FC = ({ prop1, prop2... }) => (
- // Actual code of my Component
-);
-
-export default MyComponent;
-```
-
-### Best practices for Component development in general
-
-- Only spread props `{ ... }` on the definition of the Component (Avoid having a variable named `props`)
-- Avoid importing `React`, only import the modules from React that you need
-- When importing types, use `import type { NameOfImport } from 'module'`
-- When defining a Component, use the `FC` type from React to define the type of the Component
- - When using `children` as a prop, use the `FC>` type instead
- - Alternatively you can define your type as `type MyComponentProps = PropsWithChildren<{ my other props }>`
-- Each Props type should be prefixed by the name of the Component
-- Components should always be the `default` export of a React Component file
-- Avoid using DOM/Web APIs/`document`/`window` API access within a React Component.
- Use utilities or Hooks when you need a Reactive state
-- Avoid making your Component too big. Deconstruct it into smaller Components/Hooks whenever possible
-
-## The new Downloads page
-
-### Adding a Download Installation Method
-
-To add a new download installation method, follow these steps:
-
-1. **Update `INSTALL_METHODS` in `apps/site/util/downloadUtils.tsx`:**
-
- - Add a new entry to the `INSTALL_METHODS` array.
- - Each entry should have the following properties:
- - `iconImage`: The React component of the icon image for the installation method. This should be an SVG component stored within `@node-core/ui-components/Icons/InstallationMethod` and must follow the other icon component references (being a `FC` supporting `SVGSVGElement` props).
- - Don't forget to add it on the `index.tsx` file from the `InstallationMethod` folder.
- - `recommended`: A boolean indicating if this method is recommended. This property is available only for official installation methods.
- - `url`: The URL for the installation method.
- - `value`: The key of the installation method, which must be unique.
-
- Example:
-
- ```javascript
- // filepath: /nodejs.org/apps/site/util/downloadUtils.tsx
- // See full reference of INSTALL_METHODS within `downloadUtils.tsx`
- export const INSTALL_METHODS = [
- // ...existing methods...
- {
- iconImage: ,
- url: 'https://example.com/install',
- value: 'exampleMethod',
- },
- ];
- ```
-
-2. **Add translation key in `packages/i18n/locales/en.json`:**
-
- - Add an entry under `layouts.download.codeBox.platformInfo` for the `info` property of the new installation method.
-
- Example:
-
- ```json
- // filepath: /nodejs.org/packages/i18n/locales/en.json
- {
- "layouts": {
- "download": {
- "codeBox": {
- "platformInfo": {
- "exampleMethod": "Example installation method description."
- }
- }
- }
- }
- }
- ```
-
-3. **Update `InstallationMethodLabel` and `InstallationMethod` in `apps/site/types/release.ts`:**
-
- - Add the new method to the `InstallationMethodLabel` and `InstallationMethod` types.
-
- Example:
-
- ```typescript
- // filepath: /nodejs.org/apps/site/types/release.ts
- export type InstallationMethod = 'exampleMethod' | 'anotherMethod' | ...;
-
- export const InstallationMethodLabel: Record = {
- exampleMethod: 'Example Method',
- anotherMethod: 'Another Method',
- // ...existing methods...
- };
- ```
-
-4. **Add a snippet in `apps/site/snippets/en/download`:**
-
- - Create a new file with the same key as the `value` property (e.g., `exampleMethod.bash`).
- - Add the installation instructions in this file.
- - The snippet file can use JavaScript template syntax and has access to a `props` variable of type `ReleaseContextType`.
-
- Example:
-
- ```bash
- // filepath: /nodejs.org/apps/site/snippets/en/download/exampleMethod.bash
- echo "Installing Node.js version ${props.version} using Example Method"
- ```
-
-5. **Configure `compatibility` within the `INSTALL_METHODS` object in `downloadUtils.ts`:**
-
-- Use the `compatibility` property to enable/list the installation method for specific OSs, Node.js version ranges, or architectures/platforms.
-
-Example:
-
-```javascript
-// filepath: /nodejs.org/apps/site/util/downloadUtils.tsx
-// See full reference of compatibility property within `downloadUtils.tsx`
-export const INSTALL_METHODS = [
- {
- iconImage: 'path/to/icon.svg',
- url: 'https://example.com/install',
- value: 'exampleMethod',
- compatibility: {
- os: ['LINUX', 'MAC'],
- semver: ['>=14.0.0'],
- platform: ['x64', 'arm64'],
- },
- },
-];
-```
-
-By following these steps, you can successfully add a new download installation method to the Node.js website.
-
-### Adding a Download Package Manager
-
-You can add a PACKAGE_MANAGER the same way as adding an INSTALLATION_METHOD (from the section above, "Adding a Download Installation Method") but it should be added to the PACKAGE_MANAGERS object in `apps/site/util/downloadUtils.tsx`.
-
-## Unit Tests and Storybooks
-
-Each new feature or bug fix should be accompanied by a unit test (when deemed valuable).
-We use [`node:test`][] as our test runner and [React Testing Library][] for our React unit tests.
-
-We also use [Storybook][] to document our components.
-Components within `packages/ui-components` should have a storybook story that documents the component's usage.
-
-Visual Regression Testing is automatically done via [Chromatic](https://www.chromatic.com/) to ensure that Components are rendered correctly.
-
-### General Guidelines for Unit Tests
-
-Unit Tests are fundamental to ensure that code changes do not disrupt the functionalities of the Node.js Website:
-
-- Unit tests should be written as `.mjs` files.
-- We recommend adding unit tests for content covering `util`, `scripts`, `hooks`, and `components` whenever possible.
-- Unit Tests should ensure that a given change's functionality is working as expected.
-- When creating unit tests for React components, we recommend that the tests cover all the possible states of the component.
-- We also recommend mocking external dependencies, if unsure about how to mock a particular dependency, raise the question on your Pull Request.
- - Common Providers and Contexts from the lifecycle of our App, such as [`next-intl`][] should not be mocked but given an empty or fake context whenever possible.
-- We recommend reading previous unit tests from the codebase for inspiration and code guidelines.
-
-### General Guidelines for Playwright E2E Tests
-
-End-to-end (E2E) tests are essential for ensuring that the entire application works correctly from a user's perspective:
-
-- E2E tests are located in the `apps/site/tests/e2e` directory.
-- We use [Playwright](https://playwright.dev/) as our E2E testing framework.
-- E2E tests should focus on user flows and critical paths through the application.
-- Tests should be written to be resilient to minor UI changes and should prioritize testing functionality over exact visual appearance.
-- When writing E2E tests:
- - Use meaningful test descriptions that clearly indicate what is being tested.
- - Group related tests using Playwright's test grouping features.
- - Use page objects or similar patterns to keep tests maintainable.
- - Minimize test interdependencies to prevent cascading failures.
-- Tests should run against the built application to accurately reflect the production environment.
-- We recommend reviewing existing E2E tests in the codebase for patterns and best practices.
-- If your feature involves complex user interactions or spans multiple pages, consider adding E2E tests to verify the complete flow.
-
-### General Guidelines for Storybooks
-
-Storybooks are an essential part of our development process. They help us to document our components and to ensure that the components are working as expected.
-
-They also allow Developers to preview Components and be able to test them manually/individually to the smallest unit of the Application. (The individual Component itself).
-
-**Storybooks should be fully typed and follow the following template:**
-
-```tsx
-import type { Meta as MetaObj, StoryObj } from '@storybook/react';
-import NameOfComponent from '@node-core/ui-components/PathTo/YourComponent';
-
-type Story = StoryObj;
-type Meta = MetaObj;
-
-// If the component has any props that are interactive, they should be passed here
-// We recommend reading Storybook docs for args: https://storybook.js.org/docs/react/writing-stories/args
-export const Default: Story = {};
-
-// If the Component has more than one State/Layout/Variant, there should be one Story for each variant
-export const AnotherStory: Story = {
- args: {},
-};
-
-export default { component: NameOfComponent } as Meta;
-```
-
-- Stories should have `args` whenever possible, we want to be able to test the different aspects of a Component
-- Please follow the template above to keep the Storybooks as consistent as possible
-- We recommend reading previous Storybooks from the codebase for inspiration and code guidelines.
-- If you need to decorate/wrap your Component/Story with a Container/Provider, please use [Storybook Decorators](https://storybook.js.org/docs/react/writing-stories/decorators)
-
-## Publishing Packages
-
-The Node.js Website uses a multi-package workspace architecture where individual packages are published to the npm registry. This section outlines the process for publishing packages and the best practices to follow.
-
-The package publishing process is automated through GitHub Actions and can be triggered in two ways:
-
-1. **Automatically after successful tests**:
- When changes are merged to the main branch, the "Publish Packages" workflow runs after the "Linting and Tests" workflow completes successfully. Commits must come through GitHub's merge queue (committer must be verified from noreply@github.com)
-
-2. **Manually via workflow dispatch**:
- You can manually trigger publishing for specific packages through the GitHub Actions interface. When manually triggering publishing, ensure the commit hasn't already been published and is safe to do so. In the event of a manual trigger, a Slack notification will be sent to `#nodejs-website`.
-
-## Remarks on Technologies Used
-
-The Node.js Website is a somewhat complex application and at times non-trivial solutions have been implemented to solve certain technical challenges.
-Historical decision making can be largely found on past issues, conversations on Slack and GitHub discussions. However, we also wish to highlight some of the notable development decisions that we have made here.
-
-### Why Next.js?
-
-We've found that Next.js is simply versatile, hackable, stable, community-maintained and has a great ecosystem.
-The reasoning goes deeper, but as a long-term Framework it is the most suitable choice.
-
-#### Why do we continue to support static builds?
-
-It was decided together with the TSC (Technical Steering Committee) that the Node.js Website should always support fully static builds that do not depend on any 3rd party services.
-This is to ensure that the Website is always available and that we do not depend on any 3rd party services to serve our content.
-
-(For example, if we abandon Vercel, our Website should still completely work as standalone as possible)
-
-#### What is `next.dynamic.mjs`?
-
-Our whole Website uses a custom renderer for rendering the pages.
-As you might have seen, within the `apps/site/pages` directory we have [Next.js Dynamic Route](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes) named `[...path].tsx` that matches against all possible routes of the Website.
-
-This means that each `.md(x)` file within `apps/site/pages/` is not rendered by Next.js regular App Tree (`apps/site/pages/_document.tsx` and `apps/site/pages/_app.tsx`) but a custom render tree.
-
-This custom render uses `getStaticPaths` and [Incremental Static Generation](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration) to generate the full list of supported pages of the Website.
-For example, this allows us to generate Localized Pages for every page that is not translated, by telling Next.js to create a localised path.
-`next.dynamic.mjs` is responsible for getting a full list of the source pages (`apps/site/pages/en`) and identifying which pages have been translated.
-
-Non-translated pages will have their Localized contexts and translated React message-bags (`next-intl`) but the content will be the same as the source page (English).
-Whereas localized pages will have localized context and content.
-
-This custom solution is also able to decide what paths should be compiled during runtime.
-This is a combination of rules defined on `next.constants.mjs` and `[...path].tsx`.
-
-The `[...path].tsx` file ultimately utilizes the `theme.tsx` file as its layout source.
-This setup enables the loading of the Layout Provider and MDX Provider, which in turn, encapsulate and manage the rendering of any child content or components. This includes both content and components provided by the Layout Provider and the transformed MDX content originating from the `.md(x)` source page.
-
-#### What is `next.data.mjs`?
-
-This file is responsible for loading, fetching and generating build-time required information such as Node.js Release data, Blog Posts Metadata (for pagination and indexation), RSS feeds, etc.
-
-#### What is `site.json`?
-
-This file is used for defining Website Metadata, such as which RSS feeds should be generated, Social Media Information and other Metadata used during the Website build-time.
-We use a JSON format to ease collaboration.
-
-#### What is `next.locales.mjs` and why not use Next.js built-in i18n?
-
-While Next.js provides a built-in i18n feature, it doesn't offer the flexibility we require. Our specific needs include the ability to generate comprehensive lists of supported locales and pages for each locale. Additionally, we operate with a subfolder-based approach for content, as opposed to the extension-based approach (e.g., `filename.language.md(x)`) that is compatible with Next.js's built-in i18n.
-
-We opted for the subfolder approach to maintain consistency with our previous Node.js website's content structure and to ensure long-term maintainability, rather than relying on Next.js's i18n functionality.
-
-#### What is `next.rewrites.mjs`?
-
-This file is responsible for defining the rewrite rules for the Website.
-It is used for defining redirects and other rewrite rules. (Such as Internal Redirects and External ones).
-
-The `redirects.json` file specifies two types of operations: rewrites and redirects.
-
-- Rewrites: These operations do not alter the original URL but instead render the content from the rewritten URL. It's important to note that the rewritten URL path must be valid and exist on the website.
-- Redirects: Redirect operations, on the other hand, change the original URL to a new one. While these new URLs can be either internal (within the website) or external (leading to a different domain), it is more common for redirects to point externally.
-
-This file contains a simple template engine that supports `/:locale` to indicate that this path should also be available under all available locales as prefix.
-
-#### Why do we use Next.js Middlewares?
-
-We have a simple Next.js Middleware that is responsible for handling initial Locale detection and redirection.
-It detects browser locales and redirects to the most suitable locale for the user. And it fallbacks to `/en` if no suitable locale is found.
-
-#### What are Layouts?
-
-Layouts Wrap the content of the Markdown files.
-They are responsible for adding additional styling and structure surrounding the content of the Markdown files.
-
-Layouts are defined within the `layouts` folder.
-They are React Components that receive the `children` prop, which is the transformed MDX content of the Markdown file.
-
-Each Page layout is configured within their Markdown's Frontmatter as `layout: name-of-layout`.
-
-### How we style the Website?
-
-We use [PostCSS][] to style the Node.js Website; PostCSS is a CSS Preprocessor, like Sass and Less.
-
-#### How exactly do we style Components?
-
-We style each individual React Component with a dedicated CSS file (A CSS Module) that uses CSS syntax (with the extra powerups of PostCSS).
-
-The [Styling a Component](#styling-a-component) section contains a more detailed guide on how we style our Components.
-
-#### Why we use PostCSS over Sass or Less?
-
-The main advantage of PostCSS is its minimal pluggable API that allows us to extend the native CSS-syntax with custom plugins.
-
-Next.js natively supports PostCSS and always uses PostCSS as part of the bundling and building process.
-By not using Sass or Less we remove another dependency from our build process and remove one layer of preprocessing our styles (CSS).
-
-We currently use a set of PostCSS plugins that create a SCSS-a-like environment.
-
-#### What PostCSS Plugins we use?
-
-- `postcss-calc`: Strips `calc` expressions and replaces them with the result
-- `@tailwindcss/postcss`: Allows us to use Tailwind within PostCSS
-
-It is important to mention that even though we use SCSS-like syntax, we do not use SCSS, and some of these plugins
-are not 100% compatible with the SCSS syntax.
-
-#### Do we use a CSS Framework?
-
-The Node.js Website uses Tailwind as a CSS Framework for crafting our React Components and style the Website.
-
-[Tailwind][] is an utility-first CSS Framework. It allows us to create a Design System that is easy to maintain and extend. It also allows us to create a consistent Design Language across the Website.
-
-#### Font Families on the Website
-
-We use `next/fonts` Open Sans as the default font for the Node.js Website.
-The font is configured as a CSS variable and then configured on `packages/ui-components/tailwind.config.ts` as the default font for the Website.
-
-#### Why we use RadixUI?
-
-- It is a minimalistic component library broken down in individual packages for each Component
-- It already handles all WAI-ARIA and Accessibility shortcuts/bindings needed for Interactive Elements
-- It allows us to focus on designing interactive Components without the effort of adding all the surrounding sugar and code needed to make the Component accessibility-friendly.
-
-### Why MDX?
-
-MDX is an extension on Markdown that allows us to add JSX Components within Markdown.
-Besides that, MDX is also a pluggable parser built on top of `unified` which supports Rehype and Remark Plugins.
-MDX is becoming the standard for parsing human-content on React/Next.js-based Applications.
-
-**Some of the plugins that we use include:**
-
-- `remark-gfm`: Allows us to bring GitHub Flavoured Markdown within MDX
-- `remark-headings`: Generates Metadata for Markdown Headings
- - This allows us to build the Table of Contents for each Page, for example.
-- `rehype-autolink-headings`: Allows us to add Anchor Links to Markdown Headings
-- `rehype-slug`: Allows us to add IDs to Markdown Headings
-
-#### Syntax Highlighting (Shiki) and Vercel
-
-Shiki is integrated on our workflow as a Rehype Plugin, see the `next.mdx.shiki.mjs` file. We also use the `nord` theme for Shiki and a subset of the supported languages as defined on the `shiki.config.mjs` file.
-
-### Vercel
-
-We use Vercel as our hosting provider. It is a great platform that offers an excellent CI/CD pipeline which allows us to deploy our website with ease.
-
-It is important to mention that there are some rules on our Vercel Deployments such as:
-
-- Branches starting with `dependabot` (Dependabot Automated PRs) or `gh` (GitHub Merge Queues) are not deployed to Vercel.
-- Vercel Deployments are triggered for all other branches during `push` activities.
-- We have a custom install script that executes `pnpm install --prod --frozen-lockfile` (the same way we do on our CI Pipelines)
- - Hence if Builds fail unexpectedly, make sure that your dependency that is being used during build-time is on `dependencies` and not `devDependencies`. Checkout out [DEPENDENCY_PINNING.md](./DEPENDENCY_PINNING.md) for more information.
-- Our sponsorship with Vercel is maintained by the OpenJS Foundation
-
-### Why we have a `.vscode` folder
-
-The repository defines an optimized configuration for code editing. This is optional and is not required to contribute to the project. However, the settings and extensions specified help create a uniform and more efficient developer experience. This configuration is found in the `.vscode` directory:
-
-- `extensions.json` suggests VSCode extensions that make the editor more compatible with the code. For example, a Tailwind extension creates auto-complete intellisense for tailwind styles within our components. Eslint, prettier, and editorconfig extensions read their respective config files and automatically format or lint code as written. This helps save CI feedback loops when a contribution does not meet our standards.
-- `settings.json` contains some common sense defaults that aide development and enforce consistency across the codebase. For example, we want files formatted on save and we want prettier to be used as the formatter. Without these settings, new contributors may have different authoring experiences when contributing, leading to inconsistent code and CI failures. We also disable VSCode's default CSS parser so PostCSS and Tailwind syntax are respected.
-
-Defining a `.vscode` configuration like this also aides browser-only development using [GitHub's Codespaces feature](https://github.com/features/codespaces). The web-based GUI will read these same configuration files and setup the remote development environment the same way every time.
-
-## Seeking additional clarification
-
-A lot of the current structure is due to retro-compatibility, keeping a simple and familiar file structure and keeping files that have historical reasons or needs.
-
-If you're unfamiliar or curious about something, we recommend opening a Discussion on this GitHub Repository.
-
-[`node:test`]: https://nodejs.org/api/test.html
-[React Testing Library]: https://testing-library.com/docs/react-testing-library/intro/
-[Storybook]: https://storybook.js.org/
-[`next-intl`]: https://next-intl-docs.vercel.app
-[Next.js]: https://nextjs.org/
-[MDX]: https://mdxjs.com/
-[PostCSS]: https://postcss.org/
-[React]: https://react.dev/
-[Shiki]: https://github.com/shikijs/shiki
-[Tailwind]: https://tailwindcss.com/
-[Radix UI]: https://www.radix-ui.com/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 30f6a3e310c3d..e9597648401ba 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,271 +1,40 @@
# Node.js Website Contributing Guide
-Thank you for your interest in contributing to the Node.js Website. Before you proceed, briefly go through the following:
+## Table of Contents
-- [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md)
-- [Contributing](#contributing)
- - [Becoming a Collaborator](#becoming-a-collaborator)
- - [Maintaining Collaborator Status](#maintaining-collaborator-status)
-- [Getting started](#getting-started)
- - [CLI Commands](#cli-commands)
-- [Cloudflare Deployment](#cloudflare-deployment)
-- [Commit Guidelines](#commit-guidelines)
-- [Pull Request Policy](#pull-request-policy)
-- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
-- [Adding a Learn Page](#adding-a-learn-page)
+- [Quick Start](#quick-start)
+- [Code of Conduct](#code-of-conduct)
+ - [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11)
+- [Ways to Contribute](#ways-to-contribute)
+ - [For All Contributors](#for-all-contributors)
+ - [For Developers](#for-developers)
+- [Development Workflow](#development-workflow)
+ - [1. Set Up Your Environment](#1-set-up-your-environment)
+ - [2. Make Your Changes](#2-make-your-changes)
+ - [3. Test Your Changes](#3-test-your-changes)
+ - [4. Submit Your Contribution](#4-submit-your-contribution)
+- [Documentation Structure](#documentation-structure)
+- [Getting Help](#getting-help)
+- [Project Maintainers](#project-maintainers)
+- [License](#license)
-## Contributing
+---
-Any individual is welcome to contribute to the Node.js Website. The repository currently has two kinds of contribution personas:
+Thank you for your interest in contributing to the Node.js Website! This guide will help you get started with contributing to our project.
-- A **Contributor** is any individual who creates an issue/PR, comments on an issue/PR, or contributes in some other way.
-- A **Collaborator** is a contributor with write access to the repository. See [here](#becoming-a-collaborator) on how to become a collaborator.
+## Quick Start
-You can find more details and guides about Collaborating with this repository through our [Collaborator Guide](./COLLABORATOR_GUIDE.md).
+New to contributing? Start here:
-### Becoming a Collaborator
+1. **[Getting Started](./docs/getting-started.md)** - Set up your development environment and make your first contribution
+2. **[Code Style](./docs/code-style.md)** - Learn our coding standards and formatting guidelines
+3. **[Adding Pages](./docs/adding-pages.md)** - Create new pages and content for the website
-A collaborator of the Node.js Website repository is a member of the Node.js Website Team.
+## Code of Conduct
-The Website Team is responsible for the technical development of the Node.js Website; thus, it is expected
-that team members have significant knowledge about modern Web Technologies and Web Standards.
+Before contributing, please read and follow our [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md).
-Note that regular contributors do not need to become "Collaborators" as any contribution is appreciated (even without a status), and a Collaborator status
-is a formality that comes with obligations.
-
-If you're an active contributor seeking to become a member, we recommend you contact one of the existing Team Members for guidance.
-
-
- What's the process for becoming a Collaborator?
-
-- You must be actively contributing to this repository.
-- Contributions must include significant code reviews or code contributions.
-- A nomination must be done by an existing Team Member of the Website Team with an Issue
- - The Issue must explain and describe why the nominated person is a good addition to the team
- - The Issue must contain links to relevant contributions through:
- - Code Reviews
- - Comments on Issues and PRs
- - Authoring of PRs or Issues
- - Comments or Authoring of Discussions
-- The nomination must have at least three existing members of the Website Team agree with the nomination.
- - This can be done through commenting with "agreement" (showing support) or reacting to the Issue with a :+1: (Thumbs-up Emoji)
-- The Issue must be open for at least 72 hours without an objection from an existing member of the Website Team
- - The nomination cannot pass until all open objections are resolved.
- - Objections from the TSC or Core Collaborators are also counted as valid objections.
-
-
-
-### Maintaining Collaborator Status
-
-Once you become a collaborator, you are expected to uphold certain responsibilities and standards to maintain your status:
-
-- **Adhere to Policies**: Collaborators must abide by the [Node.js Moderation Policy](https://github.com/nodejs/admin/blob/HEAD/Moderation-Policy.md) and [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md) at all times.
-
-- **Remain Active**: Collaborators are expected to author commits at least once in the past twelve months.
-
-If a collaborator becomes inactive for more than twelve months, they may be removed from the active collaborators list. They can be reinstated upon returning to active participation by going through the full nomination process again.
-
-Violations of the Code of Conduct or Moderation Policy may result in immediate removal of collaborator status, depending on the severity of the violation and the decision of the Technical Steering Committee and/or the OpenJS Foundation.
-
-## Getting started
-
-The steps below will give you a general idea of how to prepare your local environment for the Node.js Website and general steps
-for getting things done and landing your contribution.
-
-1. Click the fork button in the top right to clone the [Node.js Website Repository](https://github.com/nodejs/nodejs.org/fork)
-
-2. Clone your fork using SSH, GitHub CLI, or HTTPS.
-
- ```bash
- git clone git@github.com:/nodejs.org.git # SSH
- git clone https://github.com//nodejs.org.git # HTTPS
- gh repo clone /nodejs.org # GitHub CLI
- ```
-
-3. Change into the nodejs.org directory.
-
- ```bash
- cd nodejs.org
- ```
-
-4. Create a remote to keep your fork and local clone up-to-date.
-
- ```bash
- git remote add upstream git@github.com:nodejs/nodejs.org.git # SSH
- git remote add upstream https://github.com/nodejs/nodejs.org.git # HTTPS
- gh repo sync nodejs/nodejs.org # GitHub CLI
- ```
-
-5. Create a new branch for your work.
-
- ```bash
- git checkout -b name-of-your-branch
- ```
-
-6. Run the following to install the dependencies and start a local preview of your work.
-
- ```bash
- pnpm install --frozen-lockfile # installs this project's dependencies
- pnpm dev # starts a development environment
- ```
-
-7. Perform your changes. In case you're unfamiliar with the structure of this repository, we recommend a read on the [Collaborator Guide](./COLLABORATOR_GUIDE.md)
-
-8. Perform a merge to sync your current branch with the upstream branch.
-
- ```bash
- git fetch upstream
- git merge upstream/main
- ```
-
-9. Run `pnpm format` to confirm that linting and formatting are passing.
-
- ```bash
- pnpm format
- ```
-
-10. Once you're happy with your changes, add and commit them to your branch, then push the branch to your fork.
-
- ```bash
- cd ~/nodejs.org
- git add .
- git commit -m "describe your changes"
- git push -u origin name-of-your-branch
- ```
-
-> [!IMPORTANT]\
-> Before committing and opening a Pull Request, please go first through our [Commit](#commit-guidelines) and [Pull Request](#pull-request-policy) guidelines outlined below.
-
-11. Create a Pull Request.
-
-> [!NOTE]\
-> We ask for PR authors to avoid to rebase/update their PRs with the base branch (`main`) unnecessarily.
-> We use [GitHub Merge Queues](https://github.blog/2023-07-12-github-merge-queue-is-generally-available/)
-> which means that before merge the PRs get automatically updated and checked against the latest changes on the base branch.
->
-> This also reduces the amount of times we need to run our CI checks, as every new push requires fresh new CI-checks.
-
-### CLI Commands
-
-This repository contains several scripts and commands for performing numerous tasks. The most relevant ones are described below.
-
-
- Commands for Running & Building the Website
-
-- `pnpm dev` runs Next.js's Local Development Server, listening by default on `http://localhost:3000/`.
-- `pnpm build` builds the Application on Production mode. The output is by default within `.next` folder.
- - This is used for the Node.js Vercel Deployments (Preview & Production)
-- `pnpm deploy` builds the Application on Export Production Mode. The output is by default within `build` folder.
- - This is used for the Node.js Legacy Website Server (DigitalOcean)
-- `pnpm start` starts a web server running serving the built content from `pnpm build`
-
-
-
-
- Commands for Maintenance Tasks and Tests
-
-- `pnpm lint` runs the linter for all files.
- - `pnpm lint:fix` attempts to fix any linting errors
-- `pnpm prettier` runs the prettier for all the js files.
- - `pnpm prettier:fix` attempts to fix any style errors
-- `pnpm format` formats and fixes lints for the whole codebase
-- `pnpm scripts:release-post` generates a release post for the current release
- - **Usage:** `pnpm scripts:release-post -- --version=vXX.X.X --force`
-- `pnpm storybook` starts Storybook's local server
-- `pnpm storybook:build` builds Storybook as a static web application for publishing
-- `pnpm test` runs all tests locally
- - `pnpm test:unit` runs unit-tests locally
- - `pnpm test:ci` runs tests, and outputs data to be parsed by a CI environment
-
-
-
-## Cloudflare Deployment
-
-The Node.js Website can be deployed to the [Cloudflare](https://www.cloudflare.com) network using [Cloudflare Workers](https://www.cloudflare.com/en-gb/developer-platform/products/workers/) and the [OpenNext Cloudflare adapter](https://opennext.js.org/cloudflare). This section provides the necessary details for testing and deploying the website on Cloudflare.
-
-### Scripts
-
-Preview and deployment of the website targeting the Cloudflare network is implemented via the following two commands:
-
-- `pnpm cloudflare:preview` builds the website using the OpenNext Cloudflare adapter and runs the website locally in a server simulating the Cloudflare hosting (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/))
-- `pnpm cloudflare:deploy` builds the website using the OpenNext Cloudflare adapter and deploys the website to the Cloudflare network (using the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/))
-
-### Configurations
-
-There are two key configuration files related to Cloudflare deployment.
-
-#### Wrangler Configuration
-
-This file defines the settings for the Cloudflare Worker, which serves the website.
-
-For more details, refer to the [Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).
-
-Key configurations include:
-
-- `main`: Points to the worker generated by the OpenNext adapter.
-- `account_id`: Specifies the Cloudflare account ID. This is not required for local previews but is necessary for deployments. You can obtain an account ID for free by signing up at [dash.cloudflare.com](https://dash.cloudflare.com/login).
-- `build`: Defines the build command to generate Node.js filesystem polyfills required for the application to run on Cloudflare Workers. This uses the [`@flarelabs/wrangler-build-time-fs-assets-polyfilling`](https://github.com/flarelabs-net/wrangler-build-time-fs-assets-polyfilling) package.
-- `alias`: Maps aliases for the Node.js filesystem polyfills generated during the build process.
-- `kv_namespaces`: Contains a single KV binding definition for `NEXT_CACHE_WORKERS_KV`. This is used to implement the Next.js incremental cache. For deployments, you can create a new KV namespace in the Cloudflare dashboard and update the binding ID accordingly.
-
-#### OpenNext Configuration
-
-This is the configuration for the OpenNext Cloudflare adapter, for more details on such configuration please refer to the [official OpenNext documentation](https://opennext.js.org/cloudflare/get-started#4-add-an-open-nextconfigts-file).
-
-The configuration present here is very standard and simply sets up incremental cache via the KV binding
-defined in the wrangler configuration file.
-
-## Commit Guidelines
-
-This project follows the [Conventional Commits][] specification.
-
-Commits should be signed. You can read more about [Commit Signing][] here.
-
-### Commit Message Guidelines
-
-- Commit messages must include a "type" as described on Conventional Commits
-- Commit messages **must** start with a capital letter
-- Commit messages **must not** end with a period `.`
-
-### Pre-commit Hooks
-
-This project uses [Husky][] for Git pre-commit hooks.
-
-## Pull Request Policy
-
-This policy governs how contributions should land within this repository. The lines below state the checks and policies to be followed before merging and in the act of merging.
-
-### Before merging
-
-We recommend a read on our [Collaborator Guide](COLLABORATOR_GUIDE.md#accepting-modifications) for in-depth details on how we accept contributions into this repository.
-The list below describes some merging and approval rules adopted in this repository.
-
-- Pull Requests must be open for at least 48 hours (Or 72 hours if the PR was authored on the weekend).
- - Pull requests might be immediately merged if they contain critical bug fixes, short errata (e.g., typos from previous PRs), or any critical change considered a "showstopper" for the website's operation.
- - This kind of PRs should only be done by existing collaborators with write-access and/or signed off by administrators/maintainers.
- - This rule cannot be used for updates on the `COLLABORATOR_GUIDE.md`, `CONTRIBUTING.md` guide, `CODEOWNERS`, GitHub Actions, or any security-impacting file or document that changes the governing policies of this repository.
- - Pull requests might be "fast-tracked", meaning they can be merged before the usual 48 hours' notice if a "fast-track" label is added.
- - The person that is fast-tracking the PR (adding the label) must also comment on the PR that they're requesting the PR to be fast-tracked
- - The comment must mention `@nodejs/nodejs-website` and must have at least one ๐ (or any other sort of approval reaction) if the person fast-tracking the PR is the author of the PR.
- - Fast-tracking is only allowed for small bug fixes, small feature changes, localization changes, or other non-critical/highly-impacting changes not covered by the previous rule that allows PRs to be merged immediately.
- - Fast-tracking cannot be used for updates on the `COLLABORATOR_GUIDE.md`, `CONTRIBUTING.md` guide, `CODEOWNERS`, GitHub Actions, or any security-impacting file or document that changes the governing policies of this repository.
-- There must be no objections after forty-eight (48) hours (Or seventy-two (72) hours if the PR was authored on the weekend).
- - If there are disagreements consensus should be sought. Lack of consensus might require escalation to the Website Team Maintainers.
-- At least one approval is required for any PR to be merged.
-- Tests must be included in Pull Requests for new features or bug fixes. You are responsible for fixing any test(s) that fail.
-
-Each contribution is accepted only if there is no objection to it by a collaborator. During the review, collaborators may request that a specific contributor who is an expert in a particular area give an "LGTM" before the PR can be merged.
-
-If an objection is raised in a pull request by another collaborator, all collaborators involved should try to arrive at a consensus by addressing the concerns through discussion, compromise, or withdrawal of the proposed change(s).
-
-### When merging
-
-- All required Status-checks must have passed.
- - **Note:** If you're a collaborator, remember to run the CI checks by labeling the PR with the `github_actions:pull-request` label.
-- Please make sure that all discussions are resolved.
-- [`squash`][] pull requests made up of multiple commits
-
-## Developer's Certificate of Origin 1.1
+### Developer's Certificate of Origin 1.1
```
By contributing to this project, I certify that:
@@ -286,103 +55,89 @@ By contributing to this project, I certify that:
```
-[`squash`]: https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits
-[Conventional Commits]: https://www.conventionalcommits.org/
-[Commit Signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
-[Husky]: https://typicode.github.io/husky/
+## Ways to Contribute
-## Adding a Learn Page
+### For All Contributors
-Since the redesign of the website, we have a new section called 'Learn'. This is intended to provide a more explanatory set of resources than the API docs, which are designed purely to explain the available APIs.
+- **Report Issues**: Found a bug or have a feature request? [Open an issue](https://github.com/nodejs/nodejs.org/issues/new/choose)
+- **Improve Documentation**: Help make our docs clearer and more comprehensive
+- **Add Content**: Create new learn articles, blog posts, or improve existing content
+- **Fix Bugs**: Look for issues labeled [`good first issue`](https://github.com/nodejs/nodejs.org/labels/good%20first%20issue)
+- **Translate Content**: Help make Node.js documentation accessible worldwide
-The Learn section is separate from the API docs and is intended to provide a more narrative, tutorial style set of resources. This is a place where we can provide more context and guidance on how to use the APIs and how to build applications with them.
+### For Developers
-The Learn section is also divided into several sub-categories. Note that the sub-categories must be on the same topic.
+- **Create Components**: Build reusable React components following our [component guidelines](./docs/creating-components.md)
+- **Write Tests**: Improve test coverage with our [testing guidelines](./docs/writing-tests.md)
+- **Enhance Features**: Add new functionality to improve user experience
-### Structure of the Learn section
+## Development Workflow
-The file structure of the Learn section is as follows:
+### 1. Set Up Your Environment
-```
-site/
-โโ pages/
-โ โโ en/
-โ โ โโ learn/
-โ โ โ โโ sub-categories/
-โ โ โ โ โโ article.md
-```
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR_USERNAME/nodejs.org.git
+cd nodejs.org
-The frontmatter of the `article.md` file should look like this:
+# Install dependencies
+pnpm install --frozen-lockfile
-```yaml
-title: A super cool title
-layout: learn
-authors: github_username, another_github_username
+# Start development server
+pnpm dev
```
-A little bit of explanation about the frontmatter:
-
-- `title`: The title of the article. This will be displayed as the title of the page. We recommend that you use the same title as the navigation entry. How to enter navigation entries is explained later in this document.
-- `layout`: This must be set to `learn` so that the new article has the same style as other Learn pages.
-- `authors`: A list of the GitHub usernames of the authors of the article. This is used to display the authors' profile pictures on the page. The frontmatter must always have the `github_username` followed by `, `. The comma and space is important.
-
-### Modify the navigation
-
-The data of the navigation is stored in app/site/navigation.json. To add a new entry to the navigation, you need to add a new object to the sideNavigation.learn.
-
-```json
-{
- "sideNavigation": {
- "learn": [
- {
- "label": "Sub-category",
- "items": {
- "article": {
- "link": "/learn/sub-category/article",
- "label": "components.navigation.learn.sub-category.article"
- }
- }
- }
- ]
- }
-}
-```
+For detailed setup instructions, see [Getting Started](./docs/getting-started.md).
-The `label` key is used to display the title of the article in the navigation. To add a new i18n key we recommend you to read [the translation guide](./TRANSLATION.md#adding-new-translation-keys).
+### 2. Make Your Changes
-### Add the article
+- **New Pages**: Follow our [page creation guide](./docs/adding-pages.md)
+- **Components**: See [creating components](./docs/creating-components.md)
+- **Styling**: Follow our [code style guidelines](./docs/code-style.md)
-To add a new article, you need to create a new markdown file in the `site/pages/en/learn/your-sub-category` directory.
+### 3. Test Your Changes
-1. Create your new markdown file in the `site/pages/en/learn/your-sub-category` directory.
-2. Add the frontmatter to the file.
-3. Write your article.
-4. Add the navigation entry to `app/site/navigation.json`.
-5. Add the translation key to the translation files.
+```bash
+# Format and lint code
+pnpm format
-DONE!
+# Run tests
+pnpm test
-### Edit the article
+# Test build
+pnpm build
+```
-To edit an existing article, you need to find the markdown file in the `site/pages/en/learn/your-sub-category` directory.
+### 4. Submit Your Contribution
-> [!NOTE]
-> If you rewrite a big part of the article you can add yourself as an author in the frontmatter. **But** if you only fix a typo or a small part of the article, you don't need to add yourself as an author.
+1. **Create a branch**: `git checkout -b your-feature-branch`
+2. **Commit changes**: Follow our [commit guidelines](./docs/code-style.md#commit-guidelines)
+3. **Push to your fork**: `git push origin your-feature-branch`
+4. **Open a Pull Request**: Use our [pull request template](.github/pull_request_template.md)
-### Accessible MDX components
+## Documentation Structure
-#### Codebox
+Our documentation is organized in the [`docs/`](./docs/) directory, so check out it's **[README](./docs/README.md)** for navigation.
-The codebox component is used to display code snippets. If two code snippets follow without any text between them, they will be displayed in the same codebox, but with two tabs.
+## Getting Help
-````md
-```cjs
-const http = require('node:http');
-```
+- **Questions?** Start a [Discussion](https://github.com/nodejs/nodejs.org/discussions)
+- **Found a bug?** [Open an issue](https://github.com/nodejs/nodejs.org/issues/new/choose)
+- **Need clarification?** Comment on existing issues or PRs
+- **Want to chat?** Join the Node.js community on [OpenJS Foundation Slack](https://openjs-foundation.slack.com/)
-```mjs
-import http from 'node:http';
-```
-````
+## Project Maintainers
+
+This project is maintained by the [Node.js Website Team](https://github.com/nodejs/nodejs.org#readme). For questions about governance or high-level project direction, you can:
+
+- Mention `@nodejs/nodejs-website` in issues or PRs
+- Contact team members directly for guidance
+- Escalate to the [Node.js Technical Steering Committee](https://github.com/nodejs/TSC) if needed
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the project's [MIT License](./LICENSE).
+
+---
-`cjs` and `mjs` are variants of `js`, it's just to display the correct language in the codebox (cjs = CommonJS, mjs = ES Module).
+**Ready to contribute?** Start with our [Getting Started guide](./docs/getting-started.md) and join the Node.js community in building better web experiences for developers worldwide! ๐
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000000..80efcbe562472
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,39 @@
+# Node.js Website Documentation
+
+This directory contains documentation for contributing to the Node.js website project.
+
+## Getting Started
+
+New to contributing? Start here:
+
+- **[Getting Started](./getting-started.md)** - Set up your development environment and make your first contribution
+- **[Adding Pages](./adding-pages.md)** - Learn how to create new pages and content
+
+## Development Guidelines
+
+- **[Code Style](./code-style.md)** - Coding standards and formatting guidelines
+- **[Creating Components](./creating-components.md)** - Best practices for React component development
+- **[Writing Tests](./writing-tests.md)** - Testing guidelines for unit tests, E2E tests, and Storybooks
+
+## Technical Documentation
+
+- **[Technologies](./technologies.md)** - Overview of the tech stack and architecture decisions
+- **[Downloads Page](./downloads-page.md)** - How to add installation methods and package managers
+- **[Package Publishing](./package-publishing.md)** - Guidelines for publishing packages in our monorepo
+
+## For Collaborators
+
+- **[Collaborator Guide](./collaborator-guide.md)** - Guidelines specific to project collaborators with write access
+
+## Additional Resources
+
+- [Translation Guidelines](./translation.md) - Website translation policy
+- [Dependency Pinning](./dependency-pinning.md) - Package management guidelines
+- [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md)
+
+## Quick Reference
+
+- **Repository Structure**: See [Technologies](./technologies.md#structure-of-this-repository)
+- **Component Guidelines**: See [Creating Components](./creating-components.md)
+- **Commit Guidelines**: See [Code Style](./code-style.md#commit-guidelines)
+- **Pull Request Policy**: See [Collaborator Guide](./collaborator-guide.md#pull-request-policy)
diff --git a/docs/adding-pages.md b/docs/adding-pages.md
new file mode 100644
index 0000000000000..d44fbf8e691b0
--- /dev/null
+++ b/docs/adding-pages.md
@@ -0,0 +1,290 @@
+# Adding Pages
+
+This guide explains how to create new pages and content for the Node.js website.
+
+## Table of Contents
+
+- [Page Creation Process](#page-creation-process)
+ - [1. Create the Page Content](#1-create-the-page-content)
+ - [2. Configure the Frontmatter](#2-configure-the-frontmatter)
+ - [3. Choose the Appropriate Layout](#3-choose-the-appropriate-layout)
+ - [4. Update Navigation (if needed)](#4-update-navigation-if-needed)
+- [Adding Learn Pages](#adding-learn-pages)
+ - [Learn Page Structure](#learn-page-structure)
+ - [Learn Page Frontmatter](#learn-page-frontmatter)
+ - [Frontmatter Fields](#frontmatter-fields)
+ - [Update Learn Navigation](#update-learn-navigation)
+ - [Add Translation Keys](#add-translation-keys)
+- [Content Guidelines](#content-guidelines)
+ - [Markdown Features](#markdown-features)
+ - [Code Blocks](#code-blocks)
+ - [Multiple Code Tabs](#multiple-code-tabs)
+ - [Accessible Components](#accessible-components)
+- [File Organization](#file-organization)
+ - [Content Structure](#content-structure)
+ - [Asset Management](#asset-management)
+- [Internationalization](#internationalization)
+ - [Translation Process](#translation-process)
+ - [Translation Guidelines](#translation-guidelines)
+- [Page Types and Examples](#page-types-and-examples)
+ - [Standard Content Page](#standard-content-page)
+ - [Blog Post](#blog-post)
+ - [Learn Article](#learn-article)
+- [Validation and Testing](#validation-and-testing)
+ - [Before Publishing](#before-publishing)
+ - [Content Review](#content-review)
+- [Advanced Features](#advanced-features)
+ - [Custom Layouts](#custom-layouts)
+ - [Dynamic Content](#dynamic-content)
+
+## Page Creation Process
+
+### 1. Create the Page Content
+
+Create a new markdown file in `apps/site/pages/en/` with the appropriate subdirectory structure.
+
+```markdown
+---
+title: Title of the Page
+layout: layout-name
+---
+
+# Page Title
+
+Your content goes here...
+```
+
+### 2. Configure the Frontmatter
+
+The frontmatter (YAML block at the top) configures page metadata:
+
+- `title`: The page title displayed in the browser tab and used for SEO
+- `layout`: The layout template to use (see available layouts below)
+- `description`: Optional meta description for SEO
+- `authors`: For learn pages, list of GitHub usernames
+
+### 3. Choose the Appropriate Layout
+
+Available layouts are defined in `apps/site/layouts/`, and mapped in `components/withLayout`.
+
+### 4. Update Navigation (if needed)
+
+If your page should appear in the site navigation, update `app/site/navigation.json` as needed.
+
+## Adding Learn Pages
+
+The Learn section has special requirements and structure.
+
+### Learn Page Structure
+
+```
+apps/site/pages/en/learn/
+โโโ category-name/
+โ โโโ article-name.md
+โ โโโ another-article.md
+โโโ another-category/
+ โโโ article.md
+```
+
+### Update Learn Navigation
+
+Add your new article to `app/site/navigation.json`:
+
+```json
+{
+ "sideNavigation": {
+ "learn": [
+ {
+ "label": "Category Name",
+ "items": {
+ "articleName": {
+ "link": "/learn/category-name/article-name",
+ "label": "components.navigation.learn.category-name.article-name"
+ }
+ }
+ }
+ ]
+ }
+}
+```
+
+### Add Translation Keys
+
+Create translation keys for your navigation entries in the appropriate locale files:
+
+```json
+// packages/i18n/locales/en.json
+{
+ "components": {
+ "navigation": {
+ "learn": {
+ "category-name": {
+ "article-name": "Your Article Title"
+ }
+ }
+ }
+ }
+}
+```
+
+## Content Guidelines
+
+### Markdown Features
+
+The website supports GitHub Flavored Markdown plus MDX components:
+
+- Standard Markdown syntax
+- Code blocks with syntax highlighting
+- Tables, lists, and formatting
+- Custom React components within content
+
+### Code Blocks
+
+Use fenced code blocks with language specification:
+
+````markdown
+```javascript
+const example = 'Hello World';
+console.log(example);
+```
+````
+
+### Multiple Code Tabs
+
+Consecutive code blocks create tabbed interfaces:
+
+````markdown
+```cjs
+const http = require('node:http');
+```
+
+```mjs
+import http from 'node:http';
+```
+````
+
+When using multiple code tabs, an optional display name can be used:
+
+````markdown
+```cjs displayName="node:http"
+const http = require('node:http');
+```
+
+```mjs displayName="node:vm"
+import vm from 'node:vm';
+```
+````
+
+## File Organization
+
+### Content Structure
+
+```
+apps/site/pages/
+โโโ en/ # English content (source)
+โ โโโ learn/ # Learn section
+โ โโโ blog/ # Blog posts
+โ โโโ download/ # Download pages
+โ โโโ about/ # About pages
+โโโ {locale}/ # Translated content
+ โโโ ... # Same structure as en/
+```
+
+### Asset Management
+
+- **Images**: Store in `apps/site/public/static/images/`
+- **Documents**: Store in `apps/site/public/static/documents/`
+- **Icons**: Use existing icon system or add to `@node-core/ui-components/Icons/`
+
+## Internationalization
+
+### Translation Process
+
+1. Create the English version first in `apps/site/pages/en/`
+2. Translators will create localized versions in `apps/site/pages/{locale}/`
+3. Non-translated pages automatically fall back to English content with localized navigation
+
+### Translation Guidelines
+
+- Keep file paths consistent across locales
+- Use the same frontmatter structure
+- Reference the [Translation Guidelines](./translation.md) for detailed policies
+
+## Page Types and Examples
+
+### Standard Content Page
+
+```markdown
+---
+title: About Node.js
+layout: page
+description: Learn about the Node.js runtime and its ecosystem
+---
+
+# About Node.js
+
+Node.jsยฎ is a JavaScript runtime built on Chrome's V8 JavaScript engine...
+```
+
+### Blog Post
+
+```markdown
+---
+title: Node.js 20.0.0 Released
+layout: blog
+date: 2023-04-18
+author: Node.js Team
+---
+
+# Node.js 20.0.0 Now Available
+
+We're excited to announce the release of Node.js 20.0.0...
+```
+
+### Learn Article
+
+```markdown
+---
+title: Getting Started with Node.js
+layout: learn
+authors: nodejs-team, community-contributor
+---
+
+# Getting Started with Node.js
+
+This tutorial will guide you through...
+```
+
+## Validation and Testing
+
+### Before Publishing
+
+1. **Preview locally**: Use `pnpm dev` to preview your changes
+2. **Check formatting**: Run `pnpm format` to ensure proper formatting
+3. **Validate links**: Ensure all internal links work correctly
+4. **Test responsive design**: Check page layout on different screen sizes
+
+### Content Review
+
+- Ensure content follows our style guide
+- Verify technical accuracy
+- Check for proper grammar and spelling
+- Confirm accessibility of any custom elements
+
+## Advanced Features
+
+### Custom Layouts
+
+To create a custom layout:
+
+1. Add your layout component to `apps/site/layouts/`
+2. Update the layout mapping in `apps/site/components/withLayout.tsx`
+3. Document the layout purpose and usage
+
+### Dynamic Content
+
+For pages that need dynamic data:
+
+1. Use build-time data fetching in `apps/site/next-data/`
+2. Configure data sources in the appropriate scripts
+3. Access data through layout props or context
diff --git a/docs/code-style.md b/docs/code-style.md
new file mode 100644
index 0000000000000..f608e55e3c3a0
--- /dev/null
+++ b/docs/code-style.md
@@ -0,0 +1,225 @@
+# Code Style Guidelines
+
+This document outlines the coding standards and formatting guidelines for the Node.js website project.
+
+## Table of Contents
+
+- [Commit Guidelines](#commit-guidelines)
+ - [Commit Message Format](#commit-message-format)
+ - [Commit Signing](#commit-signing)
+ - [Examples](#examples)
+- [Pre-commit Hooks](#pre-commit-hooks)
+- [CSS Guidelines](#css-guidelines)
+ - [CSS Module Guidelines](#css-module-guidelines)
+ - [Example CSS Module](#example-css-module)
+ - [Tailwind Configuration](#tailwind-configuration)
+- [JavaScript/TypeScript Guidelines](#javascripttypescript-guidelines)
+ - [Import Standards](#import-standards)
+ - [Component Guidelines](#component-guidelines)
+ - [Example Component Structure](#example-component-structure)
+- [File Naming Conventions](#file-naming-conventions)
+ - [Components](#components)
+ - [General Files](#general-files)
+- [Linting and Formatting](#linting-and-formatting)
+ - [Automatic Formatting](#automatic-formatting)
+ - [IDE Configuration](#ide-configuration)
+- [Code Organization](#code-organization)
+ - [File Structure Standards](#file-structure-standards)
+ - [Import Organization](#import-organization)
+- [Documentation Standards](#documentation-standards)
+- [Performance Guidelines](#performance-guidelines)
+
+## Commit Guidelines
+
+This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### Commit Message Format
+
+- Commit messages must include a "type" as described in Conventional Commits
+- Commit messages **must** start with a capital letter
+- Commit messages **must not** end with a period `.`
+
+### Commit Signing
+
+Commits should be signed. You can read more about [Commit Signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) in the GitHub documentation.
+
+### Examples
+
+โ **Good commit messages:**
+
+```
+feat: Add new component for download statistics
+fix: Resolve navigation menu accessibility issue
+docs: Update contributing guidelines
+```
+
+โ **Bad commit messages:**
+
+```
+update stuff
+Fixed bug.
+added new feature
+```
+
+## Pre-commit Hooks
+
+This project uses [Husky](https://typicode.github.io/husky/) for Git pre-commit hooks to ensure code quality standards are met before commits.
+
+## CSS Guidelines
+
+We use [PostCSS](https://postcss.org/) and [Tailwind CSS](https://tailwindcss.com/) for styling. All component styles should be written in CSS Modules.
+
+### CSS Module Guidelines
+
+- Use camelCase for defining CSS classes
+- Use Tailwind's `@apply` directive to apply utility classes
+- Define one Tailwind utility class per line for better readability
+- Avoid plain CSS styles and tokens - use Tailwind utilities instead
+- Only write CSS within CSS Modules, avoid inline styles in JavaScript
+- Refer to [Tailwind's documentation](https://tailwindcss.com/docs/functions-and-directives#apply-directive) for more details
+
+### Example CSS Module
+
+```css
+.myComponent {
+ @apply flex
+ flex-col
+ items-center
+ justify-center
+ rounded-lg
+ bg-white
+ p-4
+ shadow-md;
+}
+
+.componentTitle {
+ @apply mb-4
+ text-2xl
+ font-bold
+ text-gray-900;
+}
+```
+
+## JavaScript/TypeScript Guidelines
+
+### Import Standards
+
+- Avoid importing `React` directly - only import specific modules you need
+- Use `import type` for type-only imports
+- Prefer named imports over default imports where possible
+
+### Component Guidelines
+
+- Use `FC` type from React for component definitions
+- Use `FC>` when using children prop
+- Prefix prop types with the component name
+- Always use default exports for React components
+- Avoid direct DOM/Web API access in components - use hooks or utilities instead
+
+### Example Component Structure
+
+```tsx
+import type { FC } from 'react';
+
+import styles from './index.module.css';
+
+type MyComponentProps = {
+ title: string;
+ isVisible?: boolean;
+};
+
+const MyComponent: FC = ({ title, isVisible = true }) => {
+ if (!isVisible) return null;
+
+ return (
+
+
{title}
+
+ );
+};
+
+export default MyComponent;
+```
+
+## File Naming Conventions
+
+### Components
+
+- Component folders: `PascalCase`
+- Component files: `index.tsx` (or `PascalCase.tsx` if a subdirectory is not needed)
+- Style files: `index.module.css`
+- Test files: `__tests__/index.test.mjs`
+- Story files: `index.stories.tsx`
+
+### General Files
+
+- Use `kebab-case` for most file names (i.e. documentation)
+- Use `camelCase` for utility functions and configuration files
+- Use `PascalCase` only for React components
+
+## Linting and Formatting
+
+### Automatic Formatting
+
+Run these commands to ensure your code meets our standards:
+
+```bash
+pnpm format # Formats and fixes lints for entire codebase
+pnpm lint # Run linter for all files
+pnpm lint:fix # Attempt to fix linting errors
+pnpm prettier # Run prettier for JavaScript files
+pnpm prettier:fix # Fix style errors
+```
+
+### IDE Configuration
+
+We recommend using Visual Studio Code with these extensions:
+
+- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS linting
+- [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) - Tailwind autocomplete
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - JavaScript/TypeScript linting
+- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting
+
+The repository includes a `.vscode` directory with recommended settings that will be automatically applied if you use VS Code.
+
+## Code Organization
+
+### File Structure Standards
+
+- Keep related files together in component folders
+- Use index files for clean imports
+- Group similar functionality in dedicated directories
+- Follow the established patterns in the codebase
+
+### Import Organization
+
+Organize imports in this order:
+
+1. Node.js built-in modules
+2. External library imports (Including `@node-core/*`)
+3. Relative imports (`./*`, `../*`, `#specifier/`)
+4. Type-only imports at the end of each given section
+
+```tsx
+import { readFile } from 'node:fs/promises';
+
+import { SomeComponent } from '@node-core/ui-components/Common/SomeComponent';
+import type { FC } from 'react';
+
+import { myHook } from '../hooks/myHook';
+import type { MyComponentProps } from './types';
+```
+
+## Documentation Standards
+
+- Use JSDoc comments for complex functions and utilities
+- Document component props with TypeScript interfaces
+- Include examples in Storybook for UI components
+- Keep README files updated for significant changes
+
+## Performance Guidelines
+
+- Minimize bundle size by importing only what you need
+- Use dynamic imports for large components when appropriate
+- Optimize images and assets
+- Follow React best practices for rendering performance
diff --git a/docs/collaborator-guide.md b/docs/collaborator-guide.md
new file mode 100644
index 0000000000000..973e81ce42ec6
--- /dev/null
+++ b/docs/collaborator-guide.md
@@ -0,0 +1,183 @@
+# Collaborator Guide
+
+This document contains information for Collaborators of the Node.js website project regarding maintaining the code, documentation, and issues.
+
+Collaborators should be familiar with the guidelines for new contributors in [Getting Started](./getting-started.md) and our [Code Style](./code-style.md) guidelines.
+
+## Table of Contents
+
+- [Collaborator Responsibilities](#collaborator-responsibilities)
+ - [Issues and Pull Requests](#issues-and-pull-requests)
+ - [Issue Management](#issue-management)
+ - [Pull Request Management](#pull-request-management)
+- [Accepting Modifications](#accepting-modifications)
+ - [Review Requirements](#review-requirements)
+ - [Review Process](#review-process)
+- [Pull Request Policy](#pull-request-policy)
+ - [Before Merging](#before-merging)
+ - [Timing Requirements](#timing-requirements)
+ - [Exceptions for Immediate Merging](#exceptions-for-immediate-merging)
+ - [Fast-tracking Process](#fast-tracking-process)
+ - [Consensus and Objections](#consensus-and-objections)
+ - [When Merging](#when-merging)
+ - [Required Checks](#required-checks)
+ - [Testing Requirements](#testing-requirements)
+- [Becoming a Collaborator](#becoming-a-collaborator)
+ - [Prerequisites](#prerequisites)
+ - [Application Process](#application-process)
+ - [Nomination Requirements](#nomination-requirements)
+ - [Nomination Issue Content](#nomination-issue-content)
+ - [Approval Process](#approval-process)
+ - [Maintaining Collaborator Status](#maintaining-collaborator-status)
+ - [Policy Adherence](#policy-adherence)
+ - [Activity Requirements](#activity-requirements)
+ - [Consequences of Inactivity](#consequences-of-inactivity)
+
+## Collaborator Responsibilities
+
+### Issues and Pull Requests
+
+Courtesy should always be shown to individuals submitting issues and pull requests to the Node.js website project.
+
+Collaborators should feel free to take full responsibility for managing issues and pull requests they feel qualified to handle, as long as this is done while being mindful of these guidelines, the opinions of other Collaborators and guidance of the Website Team.
+
+#### Issue Management
+
+- **Close irrelevant issues**: Collaborators may close any issue or pull request they believe is not relevant to the future of the Node.js project
+- **Allow discussion time**: When relevance is unclear, leave issues open for several days for additional discussion
+- **Re-opening**: Remember that issues can always be re-opened if necessary
+- **Seek input**: If no input from collaborators or evidence of relevance emerges, issues may be closed
+
+#### Pull Request Management
+
+> [!TIP]
+> Avoid updating/rebasing PRs unnecessarily. We use [GitHub Merge Queues](https://github.blog/2023-07-12-github-merge-queue-is-generally-available/) to merge Pull Requests, which automatically rebases and runs CI-checks against the latest merge commit.
+
+## Accepting Modifications
+
+All Node.js code and documentation modifications should be performed via GitHub pull requests. Only the Website Team can merge their work and should do so carefully.
+
+### Review Requirements
+
+- **Expert Review**: All pull requests must be reviewed and accepted by a Collaborator with sufficient expertise who can take full responsibility for the change
+- **Additional Sign-off**: Pull requests proposed by existing Collaborators require an additional Collaborator for sign-off
+- **CI Requirements**: Pull Requests can only be merged after all CI Checks have passed
+- **Manual CI Trigger**: CI Checks need to be manually triggered by adding a `github_actions:pull-request` label to the Pull Request
+
+### Review Process
+
+1. **Assess Expertise**: If you are unsure about the modification and are not prepared to take full responsibility for the change, defer to another Collaborator
+2. **Summon Experts**: In some cases, it may be necessary to summon a qualified Collaborator to a pull request for review by @-mention
+3. **Follow Guidelines**: Follow the guidelines in the [Pull Request Policy](#pull-request-policy) for reviewing and merging Pull Requests
+
+## Pull Request Policy
+
+This policy governs how contributions should land within this repository.
+
+### Before Merging
+
+#### Timing Requirements
+
+- **Minimum Open Time**: Pull Requests must be open for at least 48 hours (or 72 hours if authored on weekends).
+- **No Objections**: There must be no objections after the minimum time period
+- **At Least One Approval**: At least one approval is required for any PR to be merged
+
+#### Exceptions for Immediate Merging
+
+Pull requests might be immediately merged if they contain:
+
+- Critical bug fixes
+- Short errata (e.g., typos from previous PRs)
+- Critical changes considered "showstoppers" for the website's functionality
+
+#### Fast-tracking Process
+
+Pull requests can be "fast-tracked" (merged before 48 hours) if:
+
+1. **Label Applied**: A "fast-track" label is added
+2. **Comment Required**: The person fast-tracking must comment explaining the request
+3. **Approval Needed**: Must have at least one ๐ reaction if the fast-tracker is the PR author
+
+#### Consensus and Objections
+
+- **Seek Consensus**: If there are disagreements, consensus should be sought
+- **Escalation**: Lack of consensus might require escalation to the Website Team Maintainers
+- **Address Objections**: All objections must be addressed before merging
+- **External Objections**: Objections from TSC or Core Collaborators are valid and must be resolved
+
+### When Merging
+
+#### Required Checks
+
+- **Status Checks**: All required status checks must have passed
+- **CI Label**: Remember to run CI checks by labeling PR with `github_actions:pull-request`
+- **Discussions Resolved**: Ensure all discussions are resolved
+
+#### Testing Requirements
+
+- **Include Tests**: Tests must be included in Pull Requests for new features or bug fixes
+- **Fix Failing Tests**: Contributors are responsible for fixing any test(s) that fail
+- **Comprehensive Coverage**: Ensure tests adequately cover the changes made
+
+## Becoming a Collaborator
+
+A Collaborator of the Node.js Website repository is a member of the Node.js Website Team.
+
+### Prerequisites
+
+The Website Team is responsible for technical development of the Node.js Website, so team members should have:
+
+- Significant knowledge about modern Web Technologies
+- Understanding of Web Standards
+- Active contribution history to the repository
+
+> [!INFO]
+> Regular contributors do not need to become "Collaborators" as any contribution is appreciated, and Collaborator status is a formality that comes with obligations.
+
+### Application Process
+
+If you're an active contributor seeking to become a member, contact one of the existing Team Members for guidance.
+
+#### Nomination Requirements
+
+- **Active Contribution**: Must be actively contributing to the repository
+- **Significant Involvement**: Contributions must include significant code reviews or code contributions
+- **Team Nomination**: Nomination must be done by an existing Website Team member via GitHub Issue
+
+#### Nomination Issue Content
+
+The nomination issue must include:
+
+- Explanation of why the nominated person is a good addition to the team
+- Links to relevant contributions:
+ - Code Reviews
+ - Comments on Issues and PRs
+ - Authoring of PRs or Issues
+ - Comments or Authoring of Discussions
+
+#### Approval Process
+
+- **Three Approvals**: At least three existing Website Team members must agree (via comments or ๐ reactions)
+- **Waiting Period**: Issue must be open for at least 72 hours without objections
+- **Objection Resolution**: All objections must be resolved before proceeding
+- **External Objections**: Objections from TSC or Core Collaborators count as valid objections
+
+### Maintaining Collaborator Status
+
+Once you become a collaborator, maintain your status by:
+
+#### Policy Adherence
+
+- **Moderation Policy**: Abide by the [Node.js Moderation Policy](https://github.com/nodejs/admin/blob/HEAD/Moderation-Policy.md)
+- **Code of Conduct**: Follow the [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md)
+
+#### Activity Requirements
+
+- **Regular Commits**: Author commits at least once in the past twelve months
+- **Active Participation**: Engage in project discussions and reviews
+
+#### Consequences of Inactivity
+
+- **Twelve Month Rule**: Collaborators inactive for more than twelve months may be removed from the active collaborators list
+- **Reinstatement**: Can be reinstated upon returning to active participation through the same nomination process
+- **Policy Violations**: Violations may result in immediate removal depending on severity and TSC decision
diff --git a/CONTENT_VS_CODE.md b/docs/content-vs-code.md
similarity index 100%
rename from CONTENT_VS_CODE.md
rename to docs/content-vs-code.md
diff --git a/docs/creating-components.md b/docs/creating-components.md
new file mode 100644
index 0000000000000..38aa06aab8fcc
--- /dev/null
+++ b/docs/creating-components.md
@@ -0,0 +1,357 @@
+# Creating Components
+
+This guide covers best practices for creating React components in the Node.js website project.
+
+## Table of Contents
+
+- [Component Architecture](#component-architecture)
+- [Component Guidelines](#component-guidelines)
+ - [Framework-Agnostic Components](#framework-agnostic-components)
+ - [Website-Specific Components](#website-specific-components)
+- [Component Structure](#component-structure)
+ - [File Organization](#file-organization)
+ - [Sub-components](#sub-components)
+- [Component Implementation](#component-implementation)
+ - [Basic Component Template](#basic-component-template)
+ - [Component with Children](#component-with-children)
+- [Styling Components](#styling-components)
+ - [CSS Modules](#css-modules)
+ - [Style Guidelines](#style-guidelines)
+ - [Responsive Design](#responsive-design)
+- [TypeScript Best Practices](#typescript-best-practices)
+ - [Prop Types](#prop-types)
+ - [Import Patterns](#import-patterns)
+- [Component Domain Organization](#component-domain-organization)
+- [Testing Components](#testing-components)
+ - [Unit Tests](#unit-tests)
+ - [Storybook Stories](#storybook-stories)
+
+## Component Architecture
+
+The website uses a dual-package architecture for React components:
+
+- **`@node-core/ui-components`**: Reusable, framework-agnostic UI components
+- **`apps/site/components`**: Website-specific components that use Next.js features
+
+## Component Guidelines
+
+### Framework-Agnostic Components
+
+Generic UI components should be placed in `@node-core/ui-components`:
+
+```tsx
+// @node-core/ui-components/Common/Button/index.tsx
+import type { FC, ButtonHTMLAttributes } from 'react';
+import styles from './index.module.css';
+
+type ButtonProps = ButtonHTMLAttributes & {
+ variant?: 'primary' | 'secondary';
+ size?: 'small' | 'medium' | 'large';
+};
+
+const Button: FC = ({
+ variant = 'primary',
+ size = 'medium',
+ children,
+ className,
+ ...props
+}) => (
+
+);
+
+export default Button;
+```
+
+### Website-Specific Components
+
+Components that need Next.js features should be in `apps/site/components`, such as components that require routing.
+
+## Component Structure
+
+### File Organization
+
+Each component should have its own folder with this structure:
+
+```
+ComponentName/
+โโโ index.tsx # Component implementation
+โโโ index.module.css # Component styles
+โโโ index.stories.tsx # Storybook stories (ui-components only)
+โโโ __tests__/
+ โโโ index.test.mjs # Unit tests
+```
+
+### Sub-components
+
+If a component has sub-components, organize them hierarchically:
+
+```
+ComponentName/
+โโโ index.tsx
+โโโ index.module.css
+โโโ SubComponent/
+โ โโโ index.tsx
+โ โโโ index.module.css
+โโโ AnotherSubComponent/
+ โโโ index.tsx
+ โโโ index.module.css
+```
+
+## Component Implementation
+
+### Basic Component Template
+
+```tsx
+import type { FC } from 'react';
+import styles from './index.module.css';
+
+type MyComponentProps = {
+ title: string;
+ description?: string;
+ isVisible?: boolean;
+};
+
+const MyComponent: FC = ({
+ title,
+ description,
+ isVisible = true,
+}) => {
+ if (!isVisible) return null;
+
+ return (
+
+
{title}
+ {description &&
{description}
}
+
+ );
+};
+
+export default MyComponent;
+```
+
+### Component with Children
+
+```tsx
+import type { FC, PropsWithChildren } from 'react';
+import styles from './index.module.css';
+
+type CardProps = PropsWithChildren<{
+ title: string;
+ variant?: 'default' | 'highlighted';
+}>;
+
+const Card: FC = ({ title, variant = 'default', children }) => (
+
+
{title}
+
{children}
+
+);
+
+export default Card;
+```
+
+## Styling Components
+
+### CSS Modules
+
+Use CSS Modules for component styling:
+
+```css
+/* index.module.css */
+.container {
+ @apply flex
+ flex-col
+ gap-4
+ rounded-lg
+ bg-white
+ p-6
+ shadow-sm;
+}
+
+.title {
+ @apply text-xl
+ font-semibold
+ text-gray-900;
+}
+
+.description {
+ @apply leading-relaxed
+ text-gray-600;
+}
+```
+
+### Style Guidelines
+
+- Use camelCase for CSS class names
+- Apply one Tailwind utility per line for readability
+- Use `@apply` directive for Tailwind utilities
+- Avoid plain CSS properties when Tailwind alternatives exist
+- Keep styles scoped to the component
+
+### Responsive Design
+
+```css
+.container {
+ @apply grid
+ grid-cols-1
+ gap-4
+ md:grid-cols-2
+ lg:grid-cols-3;
+}
+
+.title {
+ @apply text-lg
+ md:text-xl
+ lg:text-2xl;
+}
+```
+
+## TypeScript Best Practices
+
+### Prop Types
+
+```tsx
+// Prefix prop types with component name
+type ButtonProps = {
+ variant: 'primary' | 'secondary' | 'danger';
+ size: 'small' | 'medium' | 'large';
+ isLoading?: boolean;
+ onClick?: () => void;
+};
+
+// Extend HTML attributes when appropriate
+type InputProps = InputHTMLAttributes & {
+ label: string;
+ error?: string;
+};
+
+// Use PropsWithChildren for components that accept children
+type ContainerProps = PropsWithChildren<{
+ maxWidth?: 'sm' | 'md' | 'lg' | 'xl';
+ className?: string;
+}>;
+```
+
+### Import Patterns
+
+```tsx
+// Type-only imports
+import type { FC, HTMLAttributes, MouseEvent } from 'react';
+
+// Regular imports
+import { useState, useEffect } from 'react';
+import { Button } from '@node-core/ui-components';
+
+// Avoid importing React itself
+// โ import React from 'react';
+// โ import type { FC } from 'react';
+```
+
+## Component Domain Organization
+
+Components should be organized by domain (where they're used):
+
+1. UI Components (`@node-core/ui-components`)
+
+When you need Next.js functionality in a UI component, use a wrapper, such as the one shown below:
+
+```tsx
+// Base component (@node-core/ui-components)
+const BaseNavLink: FC = ({ href, isActive, children }) => (
+
+ {children}
+
+);
+
+// Wrapper component (apps/site/components)
+const NavLink: FC = ({ href, children }) => {
+ const pathname = usePathname();
+ const isActive = pathname === href;
+
+ return (
+
+ {children}
+
+ );
+};
+```
+
+2. Site Components (`apps/site/components`)
+
+## Testing Components
+
+### Unit Tests
+
+```javascript
+// __tests__/index.test.mjs
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { render, screen, fireEvent } from '@testing-library/react';
+import Button from '../index.js';
+
+describe('Button Component', () => {
+ it('renders with correct text', () => {
+ render();
+ assert(isVisible(screen.getByRole('button', { name: /click me/i }));
+ });
+
+ it('applies variant styles correctly', () => {
+ render();
+ const button = screen.getByRole('button');
+ assert(button.getAttribute('class').includes('secondary'))
+ });
+});
+```
+
+### Storybook Stories
+
+```tsx
+// index.stories.tsx
+import type { Meta as MetaObj, StoryObj } from '@storybook/react';
+import Button from '@node-core/ui-components/Common/Button';
+
+type Story = StoryObj;
+type Meta = MetaObj;
+
+export const Primary: Story = {
+ args: {
+ variant: 'primary',
+ children: 'Primary Button',
+ },
+};
+
+export const Secondary: Story = {
+ args: {
+ variant: 'secondary',
+ children: 'Secondary Button',
+ },
+};
+
+export const Loading: Story = {
+ args: {
+ variant: 'primary',
+ children: 'Loading...',
+ disabled: true,
+ },
+};
+
+export default {
+ component: Button,
+ title: 'Common/Button',
+ argTypes: {
+ variant: {
+ control: 'select',
+ options: ['primary', 'secondary', 'danger'],
+ },
+ size: {
+ control: 'select',
+ options: ['small', 'medium', 'large'],
+ },
+ },
+} as Meta;
+```
diff --git a/DEPENDENCY_PINNING.md b/docs/dependency-pinning.md
similarity index 100%
rename from DEPENDENCY_PINNING.md
rename to docs/dependency-pinning.md
diff --git a/docs/downloads-page.md b/docs/downloads-page.md
new file mode 100644
index 0000000000000..1cb6e612bc2fc
--- /dev/null
+++ b/docs/downloads-page.md
@@ -0,0 +1,275 @@
+# Downloads Page
+
+This guide explains how to add and modify installation methods and package managers for the Node.js downloads page.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Adding Installation Methods](#adding-installation-methods)
+ - [1. Update Installation Methods Configuration](#1-update-installation-methods-configuration)
+ - [Configuration Properties](#configuration-properties)
+ - [2. Create Installation Icon](#2-create-installation-icon)
+ - [3. Add TypeScript Definitions](#3-add-typescript-definitions)
+ - [4. Create Installation Snippet](#4-create-installation-snippet)
+ - [Snippet Variables](#snippet-variables)
+ - [5. Add Translation Key](#5-add-translation-key)
+- [Adding Package Managers](#adding-package-managers)
+- [Compatibility Configuration](#compatibility-configuration)
+ - [Operating System Restrictions](#operating-system-restrictions)
+ - [Version Restrictions](#version-restrictions)
+ - [Platform/Architecture Restrictions](#platformarchitecture-restrictions)
+ - [Combined Restrictions](#combined-restrictions)
+- [Snippet Development](#snippet-development)
+ - [Template Syntax](#template-syntax)
+ - [Multi-line Instructions](#multi-line-instructions)
+
+## Overview
+
+The downloads page provides multiple ways for users to install Node.js across different operating systems and platforms. It supports:
+
+- **Installation Methods**: Direct ways to install Node.js (official installers, package managers, etc.)
+- **Package Managers**: Third-party package managers that can install Node.js
+- **Platform Compatibility**: OS-specific, architecture-specific, and version-specific availability
+
+## Adding Installation Methods
+
+Installation methods are the primary ways users can install Node.js. Follow these steps to add a new method:
+
+### 1. Update Installation Methods Configuration
+
+Add your new method to `apps/site/util/downloadUtils.tsx`:
+
+```javascript
+// apps/site/util/downloadUtils.tsx
+export const INSTALL_METHODS = [
+ // ...existing methods...
+ {
+ iconImage: ,
+ url: 'https://example.com/install-guide',
+ value: 'exampleMethod',
+ recommended: false, // Only for official methods
+ compatibility: {
+ os: ['LINUX', 'MAC'], // Optional: OS restrictions
+ semver: ['>=14.0.0'], // Optional: Version restrictions
+ platform: ['x64', 'arm64'], // Optional: Architecture restrictions
+ },
+ },
+];
+```
+
+#### Configuration Properties
+
+- **`iconImage`**: React component for the installation method icon
+- **`url`**: Link to official installation documentation
+- **`value`**: Unique identifier for the installation method
+- **`recommended`**: Boolean indicating if this is a recommended method (official methods only)
+- **`compatibility`**: Optional object defining when this method is available
+
+### 2. Create Installation Icon
+
+Add the icon component to `@node-core/ui-components/Icons/InstallationMethod/`:
+
+```tsx
+// @node-core/ui-components/Icons/InstallationMethod/YourIconImage.tsx
+import type { FC, SVGProps } from 'react';
+
+const YourIconImage: FC> = props => (
+
+);
+
+export default YourIconImage;
+```
+
+Update the icon index file:
+
+```tsx
+// @node-core/ui-components/Icons/InstallationMethod/index.tsx
+export { default as YourIconImage } from './YourIconImage';
+// ...other exports
+```
+
+### 3. Add TypeScript Definitions
+
+Update the type definitions in `apps/site/types/release.ts`:
+
+```typescript
+// apps/site/types/release.ts
+export type InstallationMethod =
+ | 'exampleMethod'
+ | 'anotherMethod'
+ | /* ...existing methods... */;
+
+export const InstallationMethodLabel: Record = {
+ exampleMethod: 'Example Method',
+ anotherMethod: 'Another Method',
+ // ...existing methods...
+};
+```
+
+### 4. Create Installation Snippet
+
+Add installation instructions in `apps/site/snippets/en/download/`:
+
+```bash
+# apps/site/snippets/en/download/exampleMethod.bash
+# Install Node.js ${props.version} using Example Method
+curl -fsSL https://example.com/install.sh | bash -s -- ${props.version}
+
+# Verify installation
+node --version
+npm --version
+```
+
+#### Snippet Variables
+
+The snippet has access to a `props` variable of type `ReleaseContextType`:
+
+- `props.version`: Current Node.js version (e.g., "20.0.0")
+- `props.major`: Major version number
+- `props.versionWithPrefix`: Version with "v" prefix (e.g., "v20.0.0")
+- Additional release information
+
+### 5. Add Translation Key
+
+Add descriptive text in `packages/i18n/locales/en.json`:
+
+```json
+{
+ "layouts": {
+ "download": {
+ "codeBox": {
+ "platformInfo": {
+ "exampleMethod": "Install Node.js using the Example Method package manager. This method provides automatic updates and easy version management."
+ }
+ }
+ }
+ }
+}
+```
+
+## Adding Package Managers
+
+Package managers follow the same process as installation methods but are added to the `PACKAGE_MANAGERS` configuration:
+
+```javascript
+// apps/site/util/downloadUtils.tsx
+export const PACKAGE_MANAGERS = [
+ // ...existing managers...
+ {
+ iconImage: ,
+ url: 'https://your-package-manager.com',
+ value: 'yourManager',
+ compatibility: {
+ os: ['LINUX', 'MAC', 'WIN'],
+ platform: ['x64', 'arm64'],
+ },
+ },
+];
+```
+
+Follow the same steps as installation methods, but:
+
+- Add icons to `@node-core/ui-components/Icons/PackageManager/`
+- Create snippets in `apps/site/snippets/en/download/`
+- Update `PackageManager` types instead of `InstallationMethod`
+
+## Compatibility Configuration
+
+The compatibility system allows fine-grained control over when installation methods appear:
+
+### Operating System Restrictions
+
+```javascript
+compatibility: {
+ os: ['LINUX', 'MAC', 'WIN'], // Available operating systems
+}
+```
+
+Available OS values:
+
+- `LINUX`: Linux distributions
+- `MAC`: macOS
+- `WIN`: Windows
+
+### Version Restrictions
+
+```javascript
+compatibility: {
+ semver: ['>=14.0.0', '<21.0.0'], // Supported Node.js versions
+}
+```
+
+Uses semantic versioning ranges:
+
+- `>=14.0.0`: Version 14.0.0 and higher
+- `<21.0.0`: Below version 21.0.0
+- `^18.0.0`: Compatible with 18.x.x
+- `~20.1.0`: Compatible with 20.1.x
+
+### Platform/Architecture Restrictions
+
+```javascript
+compatibility: {
+ platform: ['x64', 'arm64', 'x86'], // Supported architectures
+}
+```
+
+Available platforms:
+
+- `x64`: 64-bit x86 architecture
+- `arm64`: 64-bit ARM architecture
+- `x86`: 32-bit x86 architecture
+
+### Combined Restrictions
+
+```javascript
+compatibility: {
+ os: ['LINUX', 'MAC'],
+ semver: ['>=16.0.0'],
+ platform: ['x64', 'arm64'],
+}
+```
+
+This method would only appear for:
+
+- Linux or macOS users
+- Node.js version 16.0.0 or higher
+- 64-bit x86 or ARM architectures
+
+## Snippet Development
+
+### Template Syntax
+
+Snippets use JavaScript template literal syntax with access to release data:
+
+```bash
+# Basic usage
+echo "Installing Node.js ${props.version}"
+
+# Conditional content
+${props.major >= 18 ? '# Node.js 18+ features available' : '# Using legacy Node.js'}
+
+# Complex expressions
+curl -o nodejs.tar.gz "https://nodejs.org/dist/v${props.version}/node-v${props.version}-linux-x64.tar.gz"
+```
+
+### Multi-line Instructions
+
+```bash
+# Download and install Node.js ${props.version}
+
+# Step 1: Download the installer
+wget https://example.com/node-${props.version}-installer.sh
+
+# Step 2: Make it executable
+chmod +x node-${props.version}-installer.sh
+
+# Step 3: Run the installer
+sudo ./node-${props.version}-installer.sh
+
+# Step 4: Verify installation
+node --version # Should output: v${props.version}
+npm --version
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000000000..d293ea79826ae
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,148 @@
+# Getting Started
+
+This guide will help you set up your development environment and make your first contribution to the Node.js website.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Setting Up Your Development Environment](#setting-up-your-development-environment)
+- [Making Your First Contribution](#making-your-first-contribution)
+- [Available CLI Commands](#available-cli-commands)
+ - [Development Commands](#development-commands)
+ - [Code Quality Commands](#code-quality-commands)
+ - [Testing Commands](#testing-commands)
+ - [Other Commands](#other-commands)
+- [Next Steps](#next-steps)
+- [Getting Help](#getting-help)
+
+## Prerequisites
+
+- Node.js (latest LTS version recommended)
+- pnpm package manager
+- Git
+- A GitHub account
+
+## Setting Up Your Development Environment
+
+1. **Fork and Clone the Repository**
+
+ Click the fork button in the top right to clone the [Node.js Website Repository](https://github.com/nodejs/nodejs.org/fork)
+
+ ```bash
+ git clone git@github.com:/nodejs.org.git # SSH
+ git clone https://github.com//nodejs.org.git # HTTPS
+ gh repo clone /nodejs.org # GitHub CLI
+ ```
+
+2. **Navigate to the Project Directory**
+
+ ```bash
+ cd nodejs.org
+ ```
+
+3. **Set Up Remote Tracking**
+
+ ```bash
+ git remote add upstream git@github.com:nodejs/nodejs.org.git # SSH
+ git remote add upstream https://github.com/nodejs/nodejs.org.git # HTTPS
+ gh repo sync nodejs/nodejs.org # GitHub CLI
+ ```
+
+4. **Install Dependencies**
+
+ ```bash
+ pnpm install --frozen-lockfile
+ ```
+
+5. **Start the Development Server**
+
+ ```bash
+ pnpm dev # starts a development environment at http://localhost:3000/
+ ```
+
+## Making Your First Contribution
+
+1. **Create a New Branch**
+
+ ```bash
+ git checkout -b name-of-your-branch
+ ```
+
+2. **Make Your Changes**
+
+ - For repository structure guidance, see [Technologies](./technologies.md#structure-of-this-repository)
+ - For adding new pages, see [Adding Pages](./adding-pages.md)
+ - For component development, see [Creating Components](./creating-components.md)
+
+3. **Test Your Changes**
+
+ ```bash
+ pnpm format # runs linting and formatting
+ pnpm test # runs all tests
+ ```
+
+4. **Keep Your Branch Updated**
+
+ ```bash
+ git fetch upstream
+ git merge upstream/main
+ ```
+
+5. **Commit and Push Your Changes**
+
+ ```bash
+ git add .
+ git commit -m "describe your changes"
+ git push -u origin name-of-your-branch
+ ```
+
+ > [!TIP]
+ > Follow our [commit guidelines](./code-style.md#commit-guidelines) for commit message format.
+
+6. **Create a Pull Request**
+
+ - Go to your fork on GitHub
+ - Click "New Pull Request"
+ - Follow our [pull request guidelines](./collaborator-guide.md#pull-request-policy)
+
+## Available CLI Commands
+
+### Development Commands
+
+- `pnpm dev` - Start local development server
+- `pnpm build` - Build for production (Vercel deployments)
+- `pnpm deploy` - Build for export (Legacy server)
+- `pnpm start` - Start server with built content
+
+### Code Quality Commands
+
+- `pnpm lint` - Run linter for all files
+- `pnpm lint:fix` - Attempt to fix linting errors
+- `pnpm prettier` - Run prettier for JavaScript files
+- `pnpm prettier:fix` - Attempt to fix style errors
+- `pnpm format` - Format and fix lints for entire codebase
+
+### Testing Commands
+
+- `pnpm test` - Run all tests locally
+- `pnpm test:unit` - Run unit tests only
+- `pnpm test:ci` - Run tests with CI output format
+
+### Other Commands
+
+- `pnpm scripts:release-post -- --version=vXX.X.X --force` - Generate release post
+- `pnpm storybook` - Start Storybook development server
+- `pnpm storybook:build` - Build Storybook for publishing
+
+## Next Steps
+
+- Read about our [code style guidelines](./code-style.md)
+- Learn about [creating components](./creating-components.md)
+- Understand our [testing practices](./writing-tests.md)
+- Review the [technologies we use](./technologies.md)
+
+## Getting Help
+
+- Open a [Discussion](https://github.com/nodejs/nodejs.org/discussions) for questions
+- Check existing [Issues](https://github.com/nodejs/nodejs.org/issues) for known problems
+- Review our [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md)
diff --git a/docs/package-publishing.md b/docs/package-publishing.md
new file mode 100644
index 0000000000000..799af08baf2f0
--- /dev/null
+++ b/docs/package-publishing.md
@@ -0,0 +1,52 @@
+# Package Publishing
+
+This guide covers the package publishing process for the Node.js website's multi-package workspace architecture.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Repository Structure](#repository-structure)
+- [Publishing Process](#publishing-process)
+
+## Overview
+
+The Node.js website uses a monorepo structure where individual packages are published to the npm registry. This approach allows for:
+
+- Modular package distribution
+- Independent versioning
+- Reusable components across projects
+- Better dependency management
+
+## Repository Structure
+
+```
+nodejs.org/
+โโโ packages/
+โ โโโ ui-components/ # Reusable UI components
+โ โโโ i18n/ # Internationalization utilities
+โ โโโ [other-packages]/ # Additional packages
+โโโ apps/
+ โโโ site/ # Main website application
+```
+
+## Publishing Process
+
+Publishing is handled automatically through GitHub Actions, when changes are merged to the main branch (or via `workflow_dispatch`):
+
+1. **Merge Queue**: Changes must come through GitHub's merge queue
+2. **CI Pipeline**: "Linting and Tests" workflow completes successfully
+3. **Auto-trigger**: "Publish Packages" workflow runs automatically
+4. **Verification**: Committer must be verified from `noreply@github.com`
+5. **Notification**: Slack notification sent to `#nodejs-website` if `workflow_dispatch` was the trigger.
+
+```mermaid
+graph TD
+ A[Code Changes] --> B[Pull Request]
+ B --> C[CI Tests Pass]
+ C --> D[Merge to Main]
+ D --> E[Merge Queue]
+ E --> F[Auto Publish Trigger]
+ F --> G[Package Analysis]
+ G --> H[Version Bump]
+ H --> I[npm publish]
+```
diff --git a/docs/technologies.md b/docs/technologies.md
new file mode 100644
index 0000000000000..8f20ee7a0762b
--- /dev/null
+++ b/docs/technologies.md
@@ -0,0 +1,355 @@
+# Technologies & Architecture
+
+This document provides an overview of the technologies used in the Node.js website and explains key architectural decisions.
+
+## Table of Contents
+
+- [Core Technologies](#core-technologies)
+ - [Frontend Framework](#frontend-framework)
+ - [Why Next.js?](#why-nextjs)
+ - [Styling System](#styling-system)
+ - [PostCSS Plugins](#postcss-plugins)
+ - [Content Management](#content-management)
+ - [Content Processing Plugins](#content-processing-plugins)
+ - [UI Components](#ui-components)
+ - [Why Radix UI?](#why-radix-ui)
+ - [Internationalization](#internationalization)
+ - [Development Tools](#development-tools)
+- [Repository Structure](#repository-structure)
+- [Architecture Decisions](#architecture-decisions)
+ - [Static Build Support](#static-build-support)
+ - [Custom Page Rendering](#custom-page-rendering)
+ - [`[...path].tsx` - Dynamic Route Handler](#pathts---dynamic-route-handler)
+ - [`next.dynamic.mjs` - Page Generation](#nextdynamicmjs---page-generation)
+ - [`next.data.mjs` - Build-time Data](#nextdatamjs---build-time-data)
+ - [Internationalization Strategy](#internationalization-strategy)
+ - [Why Not Next.js Built-in i18n?](#why-not-nextjs-built-in-i18n)
+ - [Locale Detection and Routing](#locale-detection-and-routing)
+ - [Content Structure](#content-structure)
+ - [Layouts System](#layouts-system)
+ - [Content Processing Pipeline](#content-processing-pipeline)
+ - [Rewrite and Redirect System](#rewrite-and-redirect-system)
+ - [`next.rewrites.mjs`](#nextrwritesmjs)
+ - [`redirects.json`](#redirectsjson)
+- [Configuration Files](#configuration-files)
+ - [`site.json`](#sitejson)
+ - [`next.locales.mjs`](#nextlocalesmjs)
+- [Development Environment](#development-environment)
+ - [VSCode Configuration](#vscode-configuration)
+ - [Build and Deployment](#build-and-deployment)
+ - [Multiple Build Targets](#multiple-build-targets)
+ - [Vercel Integration](#vercel-integration)
+ - [Package Management](#package-management)
+ - [Multi-package Workspace](#multi-package-workspace)
+ - [Publishing Process](#publishing-process)
+- [Performance Optimizations](#performance-optimizations)
+ - [Static Generation](#static-generation)
+ - [Bundle Optimization](#bundle-optimization)
+ - [Image Optimization](#image-optimization)
+- [Testing Infrastructure](#testing-infrastructure)
+ - [Visual Regression Testing](#visual-regression-testing)
+ - [End-to-End Testing](#end-to-end-testing)
+
+## Core Technologies
+
+### Frontend Framework
+
+The Node.js Website is built with [React](https://react.dev/) and [Next.js](https://nextjs.org/):
+
+- **React**: UI rendering engine for component-based development
+- **Next.js**: Full-stack framework providing SSG, routing, and build optimization
+
+#### Why Next.js?
+
+We chose Next.js because it is:
+
+- Versatile and hackable for custom requirements
+- Stable with strong community maintenance
+- Well-suited as a long-term framework choice
+- Capable of supporting static builds (requirement from TSC)
+
+### Styling System
+
+- **[PostCSS](https://postcss.org/)**: CSS preprocessing with plugin-based architecture
+- **[Tailwind CSS](https://tailwindcss.com/)**: Utility-first CSS framework and design system foundation
+- **CSS Modules**: Scoped styling for components
+
+#### PostCSS Plugins
+
+- `postcss-calc`: Resolves `calc()` expressions at build time
+- `@tailwindcss/postcss`: Enables Tailwind integration
+
+### Content Management
+
+- **[MDX](https://mdxjs.com/)**: Markdown with JSX component support
+- **[Remark](https://github.com/remarkjs/remark)**: Markdown processing plugins
+- **[Rehype](https://github.com/rehypejs/rehype)**: HTML processing plugins
+
+#### Content Processing Plugins
+
+- `remark-gfm`: GitHub Flavored Markdown support
+- `remark-headings`: Generates metadata for table of contents
+- `rehype-autolink-headings`: Automatic anchor links for headings
+- `rehype-slug`: Automatic ID generation for headings
+
+### UI Components
+
+- **[Radix UI](https://www.radix-ui.com/)**: Accessible, unstyled component primitives
+- **[Hero Icons](https://heroicons.com/)**: SVG icon library
+- **[Shiki](https://github.com/shikijs/shiki)**: Syntax highlighting for code blocks
+
+#### Why Radix UI?
+
+- Minimalistic, component-focused approach
+- Built-in WAI-ARIA and accessibility features
+- Allows focus on design without accessibility implementation overhead
+- Modular package structure
+
+### Internationalization
+
+- **[`next-intl`](https://next-intl-docs.vercel.app)**: i18n library with Next.js integration
+- **[ICU Message Syntax](https://next-intl.dev/docs/usage/messages)**: Translation message format
+
+### Development Tools
+
+- **[Storybook](https://storybook.js.org/)**: Component development and visual testing
+- **[Chromatic](https://www.chromatic.com/)**: Automated visual regression testing
+- **[Husky](https://typicode.github.io/husky/)**: Git hooks for code quality
+
+## Repository Structure
+
+```
+nodejs.org/
+โโโ apps/
+โ โโโ site/ # Main website application
+โ โโโ components/ # Website-specific React components
+โ โโโ layouts/ # Page layout templates
+โ โโโ pages/ # Content pages (Markdown/MDX)
+โ โ โโโ en/ # English content (source)
+โ โ โโโ {locale}/ # Translated content
+โ โโโ public/ # Static assets
+โ โ โโโ static/ # Images, documents, etc.
+โ โโโ hooks/ # React hooks
+โ โโโ providers/ # React context providers
+โ โโโ types/ # TypeScript definitions
+โ โโโ next-data/ # Build-time data fetching
+โ โโโ scripts/ # Utility scripts
+โ โโโ snippets/ # Code snippets for download page
+โ โโโ tests/ # Test files
+โ โโโ e2e/ # End-to-end tests
+โโโ packages/
+ โโโ ui-components/ # Reusable UI components
+ โ โโโ styles/ # Global stylesheets
+ โ โโโ .storybook/ # Storybook configuration
+ โโโ i18n/ # Internationalization
+ โ โโโ locales/ # Translation files
+ โ โโโ config.json # Locale configuration
+ โโโ rehype-shiki/ # Syntax highlighting plugin
+ ...
+```
+
+## Architecture Decisions
+
+### Static Build Support
+
+The website supports fully static builds to ensure independence from third-party services:
+
+- Content can be served without external dependencies
+- Maintains availability even if hosting providers change
+
+### Custom Page Rendering
+
+The website uses a custom rendering system instead of Next.js default routing:
+
+#### `[...path].tsx` - Dynamic Route Handler
+
+- Catches all routes and renders them through a custom system
+- Enables dynamic page generation from Markdown files
+- Supports incremental static generation (ISG)
+
+#### `next.dynamic.mjs` - Page Generation
+
+This file handles:
+
+- Discovering all source pages in `apps/site/pages/en`
+- Identifying translated pages
+- Generating localized paths for untranslated content
+- Creating fallback pages with English content but localized navigation
+
+#### `next.data.mjs` - Build-time Data
+
+Responsible for:
+
+- Node.js release data fetching
+- Blog post metadata generation
+- RSS feed creation
+- Build-time indexing
+
+### Internationalization Strategy
+
+#### Why Not Next.js Built-in i18n?
+
+We use a custom i18n solution because:
+
+- Need comprehensive locale and page listing capabilities
+- Use subfolder content structure (`/pages/en/`, `/pages/fr/`) vs. extension-based (`file.en.md`)
+- Maintain consistency with previous website structure
+- Ensure long-term maintainability
+
+#### Locale Detection and Routing
+
+- `next.middleware.js`: Handles browser locale detection and redirects
+- Falls back to `/en` for unsupported locales
+- Provides seamless user experience across languages
+
+### Content Structure
+
+#### Layouts System
+
+```typescript
+// Each page specifies its layout in frontmatter
+---
+title: Page Title
+layout: layout-name
+---
+
+// Layouts wrap content and provide structure
+const Layout: FC<{ children: ReactNode }> = ({ children }) => (
+
+
+ {children}
+
+
+);
+```
+
+#### Content Processing Pipeline
+
+1. **Markdown files** โ MDX compiler
+2. **Rehype/Remark plugins** โ Content transformation
+3. **Shiki integration** โ Syntax highlighting
+4. **Layout system** โ Page structure
+5. **i18n integration** โ Localized rendering
+
+### Rewrite and Redirect System
+
+#### `next.rewrites.mjs`
+
+Handles URL rewriting and redirects:
+
+```javascript
+// Internal rewrites (same content, different URL)
+{ source: '/old-path', destination: '/new-path' }
+
+// External redirects (different domain)
+{ source: '/docs', destination: 'https://nodejs.org/docs' }
+
+// Locale template support
+{ source: '/:locale/old-path', destination: '/:locale/new-path' }
+```
+
+#### `redirects.json`
+
+Configuration file supporting:
+
+- Internal and external redirects
+- Locale templating with `/:locale` placeholder
+- Simple template engine for dynamic paths
+
+## Configuration Files
+
+### `site.json`
+
+Website metadata configuration:
+
+- RSS feed definitions
+- Social media information
+- Build-time metadata
+- Uses JSON format for easy collaboration
+
+### `next.locales.mjs`
+
+Locale configuration and management:
+
+- Supported locale definitions
+- Locale-specific settings
+- Page availability per locale
+
+## Development Environment
+
+### VSCode Configuration
+
+The `.vscode` directory provides:
+
+- **`extensions.json`**: Recommended extensions for optimal development
+- **`settings.json`**: Consistent formatting and linting configuration
+
+Benefits:
+
+- Uniform developer experience
+- Automatic code formatting and linting
+- Tailwind CSS IntelliSense
+- Works with GitHub Codespaces
+
+### Build and Deployment
+
+#### Multiple Build Targets
+
+- **`pnpm build`**: Production build for Vercel
+- **`pnpm deploy`**: Export build for legacy servers
+- **`pnpm dev`**: Development server
+
+#### Vercel Integration
+
+- Automatic deployments for branches (excluding `dependabot/*` and `gh/*`)
+- Custom install script: `pnpm install --prod --frozen-lockfile`
+- Dependency management: Build-time dependencies must be in `dependencies`, not `devDependencies`
+- Sponsorship maintained by OpenJS Foundation
+
+### Package Management
+
+#### Multi-package Workspace
+
+- Individual packages published to npm registry
+- Automated publishing via GitHub Actions
+- Triggered after successful CI or manual workflow dispatch
+
+#### Publishing Process
+
+1. **Automatic**: After merging to main (via merge queue)
+2. **Manual**: Workflow dispatch for specific packages
+3. **Notifications**: Slack alerts for manual triggers
+
+## Performance Optimizations
+
+### Static Generation
+
+- Build-time page generation reduces server load
+- Incremental Static Regeneration (ISR) for dynamic content
+- Optimized asset handling and compression
+
+### Bundle Optimization
+
+- Code splitting at component and route levels
+- Dynamic imports for large components
+- Tree shaking for unused code elimination
+
+### Image Optimization
+
+- Next.js Image component for automatic optimization
+- WebP conversion and responsive images
+- Lazy loading for performance
+
+## Testing Infrastructure
+
+### Visual Regression Testing
+
+- Storybook integration with Chromatic
+- Automated visual diff detection
+- Component isolation and testing
+
+### End-to-End Testing
+
+- Playwright for full application testing
+- Critical user journey validation
+- Cross-browser compatibility testing
diff --git a/TRANSLATION.md b/docs/translation.md
similarity index 100%
rename from TRANSLATION.md
rename to docs/translation.md
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
new file mode 100644
index 0000000000000..0313e9b0c0ea1
--- /dev/null
+++ b/docs/writing-tests.md
@@ -0,0 +1,177 @@
+# Writing Tests
+
+This guide covers testing practices for the Node.js website, including unit tests, end-to-end tests, and Storybook documentation.
+
+## Table of Contents
+
+- [Testing Philosophy](#testing-philosophy)
+- [Unit Testing](#unit-testing)
+- [End-to-End Testing](#end-to-end-testing)
+ - [E2E Test Guidelines](#e2e-test-guidelines)
+ - [E2E Test Structure](#e2e-test-structure)
+- [Visual Testing](#visual-testing)
+- [Visual Regression Testing](#visual-regression-testing)
+- [Running Tests](#running-tests)
+ - [Local Development](#local-development)
+ - [Continuous Integration](#continuous-integration)
+
+## Testing Philosophy
+
+Each new feature or bug fix should be accompanied by appropriate tests to ensure code quality and prevent regressions. We use multiple testing approaches:
+
+- **Unit Tests**: Test individual functions, utilities, and components in isolation
+- **End-to-End Tests**: Test complete user workflows and critical paths
+- **Visual Tests**: Automated visual regression testing via Storybook and Chromatic
+
+## Unit Testing
+
+We use [`node:test`](https://nodejs.org/api/test.html) as our test runner and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) for React component testing.
+
+```javascript
+// components/MyComponent/__tests__/index.test.mjs
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { render, screen } from '@testing-library/react';
+import MyComponent from '../index.js';
+
+describe('MyComponent', () => {
+ it('renders with default props', () => {
+ render();
+
+ const heading = screen.getByRole('heading', { name: /test title/i });
+ assert(isVisible(heading));
+ });
+});
+```
+
+## End-to-End Testing
+
+We use [Playwright](https://playwright.dev/) for end-to-end testing to ensure the entire application works correctly from a user's perspective.
+
+### E2E Test Guidelines
+
+- Tests are located in `apps/site/tests/e2e`
+- Focus on user flows and critical application paths
+- Write resilient tests that can handle minor UI changes
+- Prioritize testing functionality over exact visual appearance
+- Run tests against the built application to reflect production
+
+### E2E Test Structure
+
+```javascript
+// apps/site/tests/e2e/navigation.test.js
+import { test, expect } from '@playwright/test';
+
+test.describe('Website Navigation', () => {
+ test('user can navigate to download page', async ({ page }) => {
+ await page.goto('/');
+
+ // Click the download link in navigation
+ await page.getByRole('link', { name: /download/i }).click();
+
+ // Verify we're on the download page
+ await expect(page).toHaveURL(/.*\/download/);
+ await expect(
+ page.getByRole('heading', { name: /download node\.js/i })
+ ).toBeVisible();
+ });
+
+ test('search functionality works correctly', async ({ page }) => {
+ await page.goto('/');
+
+ // Open search
+ await page.getByRole('button', { name: /search/i }).click();
+
+ // Type search query
+ await page.getByRole('searchbox').fill('getting started');
+
+ // Verify search results appear
+ await expect(page.getByText(/search results/i)).toBeVisible();
+ });
+});
+```
+
+## Visual Testing
+
+[Storybook](https://storybook.js.org/) serves as both documentation and visual testing for our React components.
+
+```tsx
+// components/MyComponent/index.stories.tsx
+import type { Meta as MetaObj, StoryObj } from '@storybook/react';
+import MyComponent from '@node-core/ui-components/Common/MyComponent';
+
+type Story = StoryObj;
+type Meta = MetaObj;
+
+export const Default: Story = {
+ args: {
+ title: 'Default Title',
+ isVisible: true,
+ },
+};
+
+export const Hidden: Story = {
+ args: {
+ title: 'Hidden Component',
+ isVisible: false,
+ },
+};
+
+export const WithLongTitle: Story = {
+ args: {
+ title: 'This is a very long title that demonstrates text wrapping behavior',
+ isVisible: true,
+ },
+};
+
+export default {
+ component: MyComponent,
+ title: 'Common/MyComponent',
+ argTypes: {
+ isVisible: {
+ control: 'boolean',
+ description: 'Controls component visibility',
+ },
+ },
+} as Meta;
+```
+
+## Visual Regression Testing
+
+Visual regression testing is automatically handled by [Chromatic](https://www.chromatic.com/) integration with Storybook:
+
+- Runs automatically on pull requests
+- Detects visual changes in components
+- Provides approval workflow for intentional changes
+- Ensures consistent visual appearance across updates
+
+## Running Tests
+
+### Local Development
+
+```bash
+# Run all tests
+pnpm test
+
+# Run only unit tests
+pnpm test:unit
+
+# Run tests with CI formatting
+pnpm test:ci
+
+# Start Storybook for visual testing
+pnpm storybook
+
+# Build Storybook for deployment
+pnpm storybook:build
+```
+
+### Continuous Integration
+
+Tests run automatically on:
+
+- Pull request creation and updates
+- Pushes to main branch
+- Manual workflow triggers
+
+CI checks must pass before pull requests can be merged.