Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• src/data/sidebar.ts
• contentlayer.config.ts
• src/pages/[...slug].tsx
• src/layouts/DocsLayout.tsx
• src/middleware.ts
• src/types.ts

This document provides a comprehensive guide for setting up, running, and contributing to the Railway Documentation project. The project is a Next.js application responsible for rendering the content on docs.railway.com. It uses Contentlayer to manage documentation content from Markdown files and is designed to be easily developed locally and deployed automatically.

The documentation is structured to welcome contributions from the community. The core workflow involves editing Markdown files and submitting pull requests, which are then automatically deployed upon merging. This guide covers the project's technical architecture, setup process, content management system, and contribution guidelines.

Project Setup

To begin development, you need to set up the project environment on your local machine. The project requires Node.js and uses pnpm as the package manager.

Sources: README.md, package.json

Prerequisites

• Node.js: The engines field in package.json specifies Node.js version 20. The README.md also mentions Node 18, but version 20 is the declared standard. It is recommended to use a version manager like nvm.
• pnpm: The project uses pnpm for package management, as indicated by the packageManager field.

Sources: README.md:10, package.json:11, 52-54

Installation and Development

1. Install nvm and Node.js: If you don't have nvm, install it. Then run nvm install and nvm use in the project root to switch to the correct Node.js version.
2. Install Dependencies: Use pnpm to install the project dependencies:

   pnpm i
   

3. Run the Development Server: Start the Next.js development server with the following command:

   pnpm run dev
   

   This command starts the application on localhost:3001 by default.

Sources: README.md:12-17, package.json:7

The diagram below illustrates the local development setup flow.

Key Scripts

The package.json file defines several scripts for managing the application lifecycle.

Script	Description
dev	Starts the Next.js development server on port 3001 by default.
build	Runs contentlayer build to process markdown files, then runs next build to create a production-ready build of the application.
postbuild	Runs next-sitemap to generate a sitemap after the build is complete.
start	Starts the production server on port 3001 by default.
clean	Removes the .next build directory.
tsc	Runs the TypeScript compiler to check for type errors.

Sources: package.json:6-12

Project Structure

The repository is organized as a standard Next.js project with specific conventions for documentation content.

This diagram shows the key directories and how they relate to content processing and page rendering.

Sources: contentlayer.config.ts, src/data/sidebar.ts, src/pages/[...slug].tsx, src/layouts/DocsLayout.tsx

• src/docs: Contains all the documentation content as Markdown (.md) files.
• src/pages: Handles page routing for the Next.js application.
  • [...slug].tsx: Statically generates pages from the markdown files in src/docs.
  • dynamic/[...slug].tsx: Server-side renders pages, used by the middleware for specific cases like serving raw markdown.
  • api/: Contains API routes, such as llms-docs.md.ts which generates a single text file of all docs for LLM consumption.
• src/data/sidebar.ts: Defines the structure of the documentation sidebar, organizing all pages into sections and subsections.
• src/layouts/DocsLayout.tsx: The main React component that wraps every documentation page, providing the overall layout, SEO, and page navigation.
• src/components: Contains reusable React components used throughout the site.
• contentlayer.config.ts: Configures contentlayer to process the markdown files from src/docs into structured data.

Content Management with Contentlayer

The project uses contentlayer to transform Markdown files into data that can be easily consumed by the Next.js application.

Sources: contentlayer.config.ts, src/pages/[...slug].tsx

Document Schema

The contentlayer.config.ts file defines a Page document type, which specifies the structure for each markdown file.

// contentlayer.config.ts
const Page = defineDocumentType(() => ({
  name: "Page",
  filePathPattern: `**/*.md`,
  contentType: "mdx",
  fields: {
    title: {
      type: "string",
      required: true,
    },
    description: {
      type: "string",
      required: true,
    },
  },
  computedFields: {
    url: {
      type: "string",
      resolve: doc => `/${doc._raw.flattenedPath}`,
    },
  },
}));

Sources: contentlayer.config.ts:5-26

Field	Type	Required	Description
title	string	Yes	The title of the page, used in the frontmatter.
description	string	Yes	The description of the page, used in the frontmatter.
url	string	(N/A)	A computed field that generates the page URL from its path.

Sources: contentlayer.config.ts:8-25

Content Processing Flow

The build process involves contentlayer reading all .md files from src/docs, validating them against the Page schema, and generating JSON data. Next.js then uses this data to statically generate HTML pages.

This diagram shows how a markdown file is processed into a final static web page.

Sources: contentlayer.config.ts:28-31, src/pages/[...slug].tsx:57-66

Navigation and Routing

Page routing and sidebar navigation are central to the user experience. The system is designed to be flexible and data-driven.

Sidebar Structure

The sidebar's content and structure are defined in src/data/sidebar.ts. This file exports a sidebarContent array, which is a collection of sections. Each section can contain direct links to pages, or subsections with their own pages. The makePage utility helps create page objects with correctly formatted slugs.

The data structures for the sidebar are defined in src/types.ts.

This diagram shows the relationship between the different types that compose the sidebar structure.

Sources: src/data/sidebar.ts, src/types.ts:5-20

Dynamic Routing and Middleware

The application uses Next.js dynamic routes to render pages.

• src/pages/[...slug].tsx: This file is responsible for statically generating most documentation pages at build time using getStaticPaths and getStaticProps. It finds the corresponding page data from allPages (generated by Contentlayer) based on the URL slug.
• src/middleware.ts: This middleware intercepts incoming requests. Its primary roles are:
  1. To check if a requested path corresponds to a valid documentation page.
  2. To determine if the client prefers a Markdown version of the page (based on the .md extension, format=md query param, or Accept header).
  3. To rewrite the request to /dynamic/[...slug].tsx for server-side rendering. This is particularly useful for serving raw markdown content or handling server-side logic like theme detection.

The following sequence diagram illustrates the request flow for a documentation page.

Contributing

Contributions to the documentation are highly encouraged. The primary method of contribution is by editing the Markdown files directly on GitHub.

The contribution flow is as follows:

1. Find a page on docs.railway.com that you want to improve.
2. Click the "Edit this file on GitHub" link in the footer. This link is dynamically generated in DocsLayout.tsx.
3. This will take you to the corresponding .md file in the railwayapp/docs repository on GitHub.
4. Edit the file, commit your changes, and open a pull request.
5. Once the pull request is reviewed and merged, the changes are automatically deployed.

Conclusion

The Railway Documentation project is a modern, developer-friendly platform built with Next.js and Contentlayer. Its architecture prioritizes ease of local development and a streamlined contribution process. By understanding the project setup, content management flow, and routing mechanisms, developers can effectively run, maintain, and contribute to the documentation.