Skip to content

adding-pages.md

Latest commit

 

History

History
294 lines (217 loc) · 7.12 KB

adding-pages.md

File metadata and controls

294 lines (217 loc) · 7.12 KB

Adding Pages

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

Table of Contents

Page Creation Process

1. Create the Page 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...

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

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

  • canonical: The original URL of the content

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:

{
  "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:

// packages/i18n/src/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:

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

Multiple Code Tabs

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';
```

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 for detailed policies

Page Types and Examples

Standard Content Page

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

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

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