Contributing Guide

Relevant source files

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

• README.md
• package.json
• src/layouts/DocsLayout.tsx
• contentlayer.config.ts
• src/data/sidebar.ts
• src/pages/index.tsx

This guide provides instructions for contributing to the Railway Documentation. The project is a Next.js application that serves documentation from Markdown files. Contributions are welcome, and this document outlines the process for setting up the development environment, understanding the project structure, and submitting changes.

The documentation site is hosted on Railway, and deployments are handled automatically upon merging pull requests. The core of the contribution process involves editing Markdown files and creating a pull request.

Sources: README.md:5-9

Getting Started

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

Sources: README.md:11-12, package.json:11

Prerequisites

• Node.js: The project specifies version 20. It is recommended to use a version manager like nvm.
• pnpm: The project uses pnpm version 8.10.2.

Sources: README.md:11-12, package.json:11, 78

Local Development Setup

The following diagram illustrates the steps to get the development server running.

1. Install Node.js: If you have nvm, run nvm install and nvm use in the project directory. Otherwise, ensure you have Node.js version 20 installed.
2. Install Dependencies: Use pnpm to install the project's dependencies.
3. Run the Development Server: Start the Next.js development server.

# Install dependencies
pnpm i

# Run the development server
pnpm run dev

Sources: README.md:15-17

Once the server is running, you can view the documentation site by opening http://localhost:3001 in your browser.

Sources: README.md:19

Available Scripts

The project's package.json defines several scripts for development and building.

Script	Description
dev	Starts the Next.js development server on port 3001.
build	Builds the application for production.
postbuild	Generates the sitemap after a successful build.
start	Starts a Next.js production server.
clean	Removes the .next build directory.
tsc	Runs the TypeScript compiler to check for errors.

Sources: package.json:6-12

Project Structure

The documentation content is managed through Markdown files, with the site structure defined in a configuration file.

This diagram shows how Markdown files are processed by Contentlayer, structured by sidebar.ts, and rendered by Next.js pages within the DocsLayout.

Content Files

All documentation pages are written in Markdown and located in the src/docs directory. The structure of these files is defined by Contentlayer.

Sources: contentlayer.config.ts:27

Each Markdown file must include a frontmatter section with the following fields:

Field	Type	Required	Description
title	string	Yes	The title of the page.
description	string	Yes	The description of the page.

Sources: contentlayer.config.ts:11-20

Here is an example of the Page document type definition:

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

Sources: contentlayer.config.ts:6-26

Sidebar Navigation

The navigation sidebar is defined in src/data/sidebar.ts. To add a new page to the documentation, you must add an entry to this file.

The makePage helper function is used to create page objects.

// src/data/sidebar.ts
const makePage = (title: string, category?: string, slug?: string): IPage => ({
  title,
  category,
  slug: (() => {
    if (slug) {
      return slug.startsWith("/") ? slug : "/" + slug;
    }

    return "/" + (category ? category + "/" : "") + slugify(title);
  })(),
});

Sources: src/data/sidebar.ts:4-14

To add a new page under the "Overview" section, you would modify the sidebarContent array:

// src/data/sidebar.ts
export const sidebarContent: ISidebarContent = [
  // ... other sections
  {
    title: "Overview",
    content: [
      makePage("About Railway", "overview"),
      makePage("The Basics", "overview"),
      makePage("Best Practices", "overview"),
      makePage("Advanced Concepts", "overview"),
      // Add your new page here
      makePage("My New Page", "overview"),
    ],
  },
  // ... other sections
];

Sources: src/data/sidebar.ts:23-30

How to Contribute

Contributions primarily involve editing Markdown files. The process is designed to be simple and leverages GitHub's interface.

Contribution Flow

The general workflow for making a contribution is as follows:

Editing a Page

Every documentation page includes an "Edit this file on GitHub" link in the footer. This link will take you directly to the source Markdown file on GitHub for editing.

The link is constructed dynamically in the DocsLayout.tsx component.

// src/layouts/DocsLayout.tsx
const gitHubFileLink = useMemo(
  () =>
    `https://github.com/railwayapp/docs/edit/main/src/docs%24%7BprefixedSlug%7D.md%60%2C
  [prefixedSlug],
);

Sources: src/layouts/DocsLayout.tsx:64-68

After making your changes in the GitHub editor, you can commit them and create a pull request for the project maintainers to review.

Sources: README.md:7, src/pages/index.tsx:399-405

Summary

Contributing to the Railway documentation is a straightforward process. By setting up a local development environment, you can preview your changes. The main contribution method is editing the Markdown files located in src/docs and submitting a pull request. The structure is managed by contentlayer.config.ts for content types and src/data/sidebar.ts for navigation, making it easy to add or modify content.