Skip to main content
This guide walks through creating a new page and publishing it on the Node.js website.

​
Quick Reference

1

Create the content file

Add a new .md or .mdx file in apps/site/pages/en/ under the appropriate subdirectory.
2

Configure frontmatter

Add the required YAML frontmatter block at the top of the file.
3

Choose a layout

Set the layout frontmatter field to one of the available layouts in apps/site/layouts/.
4

Update navigation (if needed)

If the page should appear in the sidebar, update apps/site/navigation.json.
5

Preview locally

Run pnpm dev and navigate to the new page URL.

​
1. Create the Content File

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

​
Learn Page Structure

Learn pages follow a category/article hierarchy: 
apps/site/pages/en/learn/
├── getting-started/
│   ├── introduction-to-nodejs.md
│   └── debugging.md
└── my-new-category/
    └── my-new-article.md

​
2. Configure the Frontmatter

The YAML frontmatter at the top of the file controls page metadata: 
---
title: About Node.js
layout: about
description: Learn about the Node.js runtime and its ecosystem
authors: nodejs-team, community-contributor
canonical: https://original-source.example.com/the-article
---
FieldRequiredDescription
titleYesBrowser tab title and SEO <title> tag
layoutYesLayout template name (see available layouts below)
descriptionNoSEO meta description
authorsNoGitHub usernames for learn articles; shown in the meta bar
canonicalNoOriginal URL for syndicated content

​
3. Choose the Appropriate Layout

Available layouts are defined in apps/site/layouts/ and mapped in apps/site/components/withLayout.tsx.
Layout nameFileBest for
aboutAbout.tsxAbout section pages with sidebar navigation
article-pageArticlePage.tsxStandalone article pages with meta bar
blogBlog.tsxBlog index and category listing pages
defaultDefault.tsxGeneric pages with no sidebar
downloadDownload.tsxDownload pages with release data integration
download-archiveDownloadArchive.tsxDownload archive listing
glowing-backdropGlowingBackdrop.tsxLanding/feature pages with visual treatment
learnLearn.tsxLearn section articles with sidebar and cross-links
postPost.tsxIndividual blog posts with author and category

​
4. Update Navigation

​
Top Navigation

The topNavigation key in apps/site/navigation.json controls the main navbar links: 
{
  "topNavigation": {
    "learn": {
      "link": "/learn",
      "label": "components.containers.navBar.links.learn"
    }
  }
}

​
Side Navigation (Learn)

To add a Learn article to the sidebar, add an entry to the sideNavigation.learn.items object in navigation.json: 
{
  "sideNavigation": {
    "learn": {
      "items": {
        "myNewCategory": {
          "label": "components.navigation.learn.myNewCategory.links.myNewCategory",
          "items": {
            "myNewArticle": {
              "link": "/learn/my-new-category/my-new-article",
              "label": "components.navigation.learn.myNewCategory.links.myNewArticle"
            }
          }
        }
      }
    }
  }
}

​
Add Translation Keys

Navigation labels are translation keys, not raw strings. Add the corresponding key/value pair to packages/i18n/locales/en.json: 
{
  "components": {
    "navigation": {
      "learn": {
        "myNewCategory": {
          "links": {
            "myNewCategory": "My New Category",
            "myNewArticle": "My New Article Title"
          }
        }
      }
    }
  }
}
Only add new translation keys to packages/i18n/locales/en.json. Crowdin automatically syncs new keys to translators. New keys should be added at the bottom of the file so translators can spot them easily.

​
Page Type Examples

---
title: About Node.js
layout: about
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...

​
Validation and Testing

Before opening a pull request:
  1. Preview locally: Run pnpm dev and navigate to your page
  2. Check formatting: Run pnpm format to ensure consistent formatting
  3. Validate links: Confirm all internal links resolve correctly
  4. Test responsiveness: Check the layout on different screen sizes

​
Dynamic Content Pages

For pages that need build-time data (e.g., release listings):
  1. Add a data provider in apps/site/next-data/
  2. Configure the data source in the appropriate script
  3. Access data through layout props or React context
See apps/site/next-data/providers/releaseData.ts for a real example used by the Download layout.

Build docs developers (and LLMs) love

Get started for freeTalk to us