Configuration Files

Relevant source files

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

• package.json
• contentlayer.config.ts
• tailwind.config.js
• meilisearch-docs-scraper.config.json
• next-sitemap.config.js
• src/middleware.ts
• src/pages/[...slug].tsx

The railways-docs project relies on a set of configuration files to manage its structure, build process, content, styling, and deployment. These files define everything from project dependencies and scripts to how Markdown content is processed and indexed for search. Understanding these configurations is key to contributing to and maintaining the documentation platform.

This document provides a detailed breakdown of the primary configuration files, explaining their purpose and key settings. The configurations work in concert to power the Next.js application, enabling features like content-driven pages, a flexible styling system, and robust SEO and search capabilities.

Project & Build Configuration

package.json

This file is the manifest for the Node.js project. It defines metadata, lists all dependencies, and specifies the scripts used for development, building, and starting the application.

Sources: package.json

Key Scripts

The scripts section contains commands for managing the application lifecycle.

Script	Command	Description
dev	next dev --port ${PORT-3001}	Starts the Next.js development server on port 3001 by default.
build	contentlayer build && next build	Builds the application for production. It first runs Contentlayer to generate data from Markdown, then builds the Next.js app.
postbuild	next-sitemap	Runs after the build to generate a sitemap.
start	next start --port ${PORT-3001}	Starts the production Next.js server.

Sources: package.json:6-11

Dependencies

The project uses several key libraries:

• next: The React framework for building the application.
• contentlayer & next-contentlayer: For transforming Markdown content into data that can be used in Next.js pages.
• tailwindcss: A utility-first CSS framework for styling.
• twin.macro: Allows using Tailwind CSS classes with CSS-in-JS libraries like styled-components.
• meilisearch: The client for the search functionality.

Sources: package.json:14-43

Engine & Babel Configuration

The project specifies a required Node.js version and configures Babel for twin.macro.

  "engines": {
    "node": "20"
  },
  "babelMacros": {
    "twin": {
      "preset": "styled-components"
    }
  }

• engines: Enforces the use of Node.js version 20.
• babelMacros: Configures the twin.macro library to use styled-components as its preset.

Sources: package.json:45-51

next-sitemap.config.js

This file configures the next-sitemap package, which automatically generates sitemap.xml and robots.txt files for search engine optimization (SEO).

module.exports = {
  siteUrl: process.env.NEXT_PUBLIC_RAILWAY_DOCS_URL || "https://docs.railway.com",
  generateRobotsTxt: true,
};

• siteUrl: Sets the base URL for all pages in the sitemap. It uses the NEXT_PUBLIC_RAILWAY_DOCS_URL environment variable, with a fallback to the production URL.
• generateRobotsTxt: When true, it creates a robots.txt file, which instructs web crawlers on how to crawl the site.

Sources: next-sitemap.config.js

Content & Styling

contentlayer.config.ts

Contentlayer is configured here to process Markdown files from src/docs into structured data. It defines the schema for the documentation pages and sets up MDX processing plugins.

Sources: contentlayer.config.ts

The diagram below illustrates the flow of content from a Markdown file through Contentlayer to the Next.js application.

Page Schema

A Page document type is defined with the following structure:

Field	Type	Required	Description
title	string	Yes	The title of the page.
description	string	Yes	The description of the page.
url	string	(Computed)	The URL path, derived from the file path (e.g., /guides/projects).

Sources: contentlayer.config.ts:6-24

MDX Plugins

The configuration uses remark plugins to enhance the Markdown processing:

• remarkSlug: Adds id attributes to headings.
• remarkAutoLinkHeadings: Wraps headings in anchor links.
• remarkGfm: Adds support for GitHub Flavored Markdown features like tables.

Sources: contentlayer.config.ts:27

tailwind.config.js

This file configures the Tailwind CSS framework, defining the design system including colors, fonts, and custom styles for the documentation content.

Sources: tailwind.config.js

Theme Configuration

• Dark Mode: Enabled using the class strategy, allowing toggling via a class on the <html> element.
• Content Scanning: Tailwind scans all .js, .ts, .jsx, and .tsx files in the src directory to tree-shake unused styles.
• Colors: A custom color palette is defined using CSS variables (e.g., var(--colors-gray-100)), which facilitates theming.
• Typography: The @tailwindcss/typography plugin is used to style the "prose" content rendered from Markdown. It sets default styles for elements like headings, links, and code blocks. For example, links are underlined and turn pink on hover.

// Example of typography plugin configuration
typography: theme => ({
  DEFAULT: {
    css: {
      color: theme("colors.foreground"),
      a: {
        color: "currentColor",
        textDecoration: "underline",
        "&:hover": {
          color: theme("colors.pink.500"),
        },
      },
      // ... other styles
    },
  },
}),

Sources: tailwind.config.js:33-76

Search Indexing

meilisearch-docs-scraper.config.json

This configuration file instructs the Meilisearch scraper on how to index the documentation site for the search feature. It defines the starting URL, content selectors, and custom settings for the index.

Sources: meilisearch-docs-scraper.config.json

The diagram below shows how the scraper processes the documentation site.

Configuration Details

Key	Value	Description
index_uid	docs_railway_app_production	The unique identifier for the search index.
start_urls	["https://docs.railway.com/"]	The URL where the scraper begins crawling.
selectors	(Object)	CSS selectors used to extract content and build a hierarchy (e.g., lvl0, lvl1, text).
custom_settings	(Object)	Defines custom index settings, such as synonyms to treat terms like postgres and postgresql as equivalent.

Sources: meilisearch-docs-scraper.config.json:2-25

Routing

src/middleware.ts

The project uses Next.js middleware to handle routing for documentation pages. It intercepts requests and rewrites them to a dynamic route handler (/dynamic/[...slug]) based on certain conditions. This allows serving either the standard HTML page or the raw Markdown content.

A request for a documentation page is handled as follows:

1. The middleware checks if the requested path (e.g., /guides/projects) exists in the set of pages generated by Contentlayer.
2. It then determines if the user is requesting Markdown content. This is true if:
   • The path ends with .md.
   • The query parameter format=md is present.
   • The Accept HTTP header prefers text/markdown over text/html.
3. The request is rewritten to /dynamic/[...slug]. If Markdown was requested, the format=md query parameter is added.

Sources: src/middleware.ts:5-30