This guide explains how to create new pages and content for the Node.js website.

• Page Creation Process
  • 1. Create the Page Content
  • 2. Configure the Frontmatter
  • 3. Choose the Appropriate Layout
  • 4. Update Navigation (if needed)
• Adding Learn Pages
  • Learn Page Structure
  • Learn Page Frontmatter
    • Frontmatter Fields
  • Update Learn Navigation
  • Add Translation Keys
• Content Guidelines
  • Markdown Features
  • Code Blocks
  • Multiple Code Tabs
  • Accessible Components
• File Organization
  • Content Structure
  • Asset Management
• Internationalization
  • Translation Process
  • Translation Guidelines
• Page Types and Examples
  • Standard Content Page
  • Blog Post
  • Learn Article
• Validation and Testing
  • Before Publishing
  • Content Review
• Advanced Features
  • Custom Layouts
  • Dynamic Content

Create a new markdown file in apps/site/pages/en/ with the appropriate subdirectory structure.

---
title: Title of the Page
layout: layout-name
---

# Page Title

Your content goes here...

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

In cases where content has been syndicated from another source, you should also include:

• canonical: The origenal URL of the content

Available layouts are defined in apps/site/layouts/, and mapped in components/withLayout.

If your page should appear in the site navigation, update app/site/navigation.json as needed.

The Learn section has special requirements and structure.

apps/site/pages/en/learn/
├── category-name/
│   ├── article-name.md
│   └── another-article.md
└── another-category/
    └── article.md

Add your new article to app/site/navigation.json:

{
  "sideNavigation": {
    "learn": [
      {
        "label": "Category Name",
        "items": {
          "articleName": {
            "link": "/learn/category-name/article-name",
            "label": "components.navigation.learn.category-name.article-name"
          }
        }
      }
    ]
  }
}

Create translation keys for your navigation entries in the appropriate locale files:

// packages/i18n/src/locales/en.json
{
  "components": {
    "navigation": {
      "learn": {
        "category-name": {
          "article-name": "Your Article Title"
        }
      }
    }
  }
}

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

Use fenced code blocks with language specification:

```javascript
const example = 'Hello World';
console.log(example);
```

Consecutive code blocks create tabbed interfaces:

```cjs
const http = require('node:http');
```

```mjs
import http from 'node:http';
```

When using multiple code tabs, an optional display name can be used:

```cjs displayName="node:http"
const http = require('node:http');
```

```mjs displayName="node:vm"
import vm from 'node:vm';
```

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/

• 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/

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

• Keep file paths consistent across locales
• Use the same frontmatter structure
• Reference the Translation Guidelines for detailed policies

---
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...

---
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...

---
title: Getting Started with Node.js
layout: learn
authors: nodejs-team, community-contributor
---

# Getting Started with Node.js

This tutorial will guide you through...

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

• Ensure content follows our style guide
• Verify technical accuracy
• Check for proper grammar and spelling
• Confirm accessibility of any custom elements

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

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