Project Overview

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/layouts/DocsLayout.tsx
• src/pages/[...slug].tsx
• src/middleware.ts
• src/pages/api/llms-docs.md.ts
• src/components/SEO.tsx
• meilisearch-docs-scraper.config.json
• src/types.ts

The railways-docs project is the official documentation website for Railway, available at docs.railway.com. It is a modern, open-source documentation platform built using Next.js. The site serves user guides, quickstarts, tutorials, and reference materials. It is designed for community contributions, with a streamlined process for suggesting and merging changes via GitHub pull requests.

The architecture is centered around a static content pipeline using Markdown files, which are processed and rendered as static pages for optimal performance. Key features include a robust search powered by Meilisearch, comprehensive SEO with structured data, and a special API endpoint to provide documentation content for LLM consumption.

Sources: README.md, package.json, src/pages/index.tsx:11-20

Core Technologies

The project leverages a modern web development stack to deliver a fast and feature-rich documentation experience. The primary technologies are defined in the package.json file.

The diagram below illustrates the main technologies used in the project.

Technology	Role
Next.js	The core React framework for building the static and server-rendered pages.
React	The UI library for building components.
TypeScript	Provides static typing for the entire codebase.
Contentlayer	Transforms Markdown/MDX content from src/docs into type-safe JSON data for Next.js.
twin.macro	A library that blends the power of Tailwind CSS with CSS-in-JS (Styled Components).
Meilisearch	Powers the documentation search functionality.
pnpm	The package manager used for dependency management.

Sources: package.json:13-44, contentlayer.config.ts

Content Management and Rendering

The core of the documentation site is its content pipeline, which transforms Markdown files into statically generated HTML pages. This process is augmented by a middleware for dynamic routing and content negotiation.

The following diagram shows the flow from a user request to a rendered page.

Content Source and Processing

All documentation content resides as Markdown (.md) files within the src/docs directory. Contentlayer is configured in contentlayer.config.ts to watch this directory.

• defineDocumentType: Defines the schema for a Page, which includes required title and description fields, and a computed url.
• makeSource: The main configuration function that specifies the content directory (src/docs), document types, and MDX/remark plugins.
• Remark Plugins: remark-slug, remark-autolink-headings, and remark-gfm are used to add slugs to headings, create anchor links, and support GitHub Flavored Markdown, respectively.

Sources: contentlayer.config.ts:5-24

Page Rendering and Routing

The project uses a combination of static and server-side rendering, with a clever middleware to handle different request types.

1. Middleware (src/middleware.ts):

   • Intercepts all incoming requests.
   • It checks if the requested path corresponds to a known documentation page.
   • It determines if the user agent prefers Markdown over HTML (e.g., a curl request with an Accept: text/markdown header) or if the URL contains ?format=md.
   • It rewrites the URL to /dynamic/[...slug], adding ?format=md if necessary. This allows a single page component to handle both HTML and raw Markdown responses.

   Sources: src/middleware.ts:5-32

2. Dynamic Page (src/pages/dynamic/[...slug].tsx):

   • This page uses getServerSideProps to handle requests rewritten by the middleware.
   • It finds the corresponding page data from Contentlayer.
   • If ?format=md is present, it reconstructs the full Markdown content (with frontmatter) and sends it as a text/markdown response.
   • Otherwise, it passes the page data, raw markdown, and theme cookie (colorModeSSR) to the React component for HTML rendering.
   • The useMDXComponent hook renders the MDX content, mapping custom components like <CodeBlock>, <Banner>, and <Collapse>.

   Sources: src/pages/dynamic/[...slug].tsx

3. Static Fallback (src/pages/[...slug].tsx):

   • This file uses getStaticPaths and getStaticProps to pre-render all documentation pages at build time. This ensures fast initial page loads for standard browser navigation.
   • The middleware effectively overrides this for most live requests, but it's a key part of the Next.js static site generation (SSG) strategy.

   Sources: src/pages/[...slug].tsx:70-89

Key Features

Documentation Structure

The navigation sidebar and overall structure of the documentation are centrally managed in src/data/sidebar.ts. This file exports a sidebarContent array, which defines the sections, subsections, and pages.

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

This diagram shows the TypeScript types that define the sidebar's hierarchical structure.
Sources: src/data/sidebar.ts, src/types.ts:7-23

A helper function flattenSidebarContent in DocsLayout.tsx is used to create a flat list of all pages, which is then used to determine the "Previous" and "Next" page links at the bottom of each document.

Sources: src/layouts/DocsLayout.tsx:28-52, src/layouts/DocsLayout.tsx:93-101

Search Functionality

Search is implemented using Meilisearch. The configuration for the web scraper is located in meilisearch-docs-scraper.config.json.

Scraper Setting	Description
index_uid	docs_railway_app_production
start_urls	https://docs.railway.com/
selectors	Defines CSS selectors for different heading levels (lvl0 to lvl4) and body text (text) to build a search hierarchy.
custom_settings	Configures synonyms, e.g., mapping postgres to postgresql.

Sources: meilisearch-docs-scraper.config.json

The search UI is handled by React components, with src/components/Search/Results.tsx being responsible for rendering the search results, handling keyboard navigation (ArrowUp, ArrowDown, Enter), and linking to the correct page and hash.

Sources: src/components/Search/Results.tsx

SEO and Structured Data

The project has a strong focus on Search Engine Optimization (SEO), managed primarily by the SEO.tsx component.

• Dynamic Metadata: It generates page titles, descriptions, canonical URLs, and Open Graph images for social sharing.
• Structured Data (JSON-LD): It automatically generates several schema types to provide rich context to search engines:
  • Organization: Describes Railway as an organization.
  • BreadcrumbList: Built dynamically from the sidebar structure using buildBreadcrumbs utility.
  • Article: Provides details about the current documentation page, including author, publisher, and modification dates.
  • ItemList (Table of Contents): Generated from the headers extracted from the markdown content.
  • FAQPage: If any headers on the page are questions (end with "?"), an FAQ schema is automatically created.

Sources: src/components/SEO.tsx, src/utils/seo.ts

API for LLM Consumption

A unique feature is the /api/llms-docs.md API endpoint, which is designed to provide the entire documentation content in a single, clean text file for consumption by Large Language Models (LLMs).

The process is as follows:

This flow ensures that an LLM can get a structured, text-only version of the documentation without the noise of HTML or complex Markdown syntax.

Sources: src/pages/api/llms-docs.md.ts

Development and Deployment

Development Workflow

The development process is standard for a Next.js project and is outlined in README.md.

1. Install Dependencies: pnpm i
2. Run Dev Server: pnpm run dev
3. Access: Open http://localhost:3001

The package.json file contains the necessary scripts for development (dev), building (build), and starting the production server (start).

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

Deployment

The documentation is hosted on Railway. Deploys are triggered automatically when pull requests are merged into the main branch. The postbuild script runs next-sitemap to generate a sitemap for the deployed site.

Sources: README.md:8-9, package.json:8, next-sitemap.config.js.