Project Structure

Relevant source files

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

• package.json
• contentlayer.config.ts
• src/data/sidebar.ts
• src/types.ts
• src/layouts/DocsLayout.tsx
• src/pages/[...slug].tsx
• src/pages/dynamic/[...slug].tsx
• src/middleware.ts
• src/pages/api/llms-docs.md.ts
• src/components/SEO.tsx
• README.md

This project is a documentation website built using the Next.js framework. Its primary purpose is to render Markdown-based documentation into a fast, static, and SEO-friendly website. The architecture relies on Contentlayer for processing content, TypeScript for type safety, and Tailwind CSS (via twin.macro) for styling.

The core of the project involves transforming Markdown files located in the src/docs directory into structured, type-safe JSON data during the build process. This data is then used by Next.js to statically generate HTML pages, providing excellent performance and user experience. The structure also includes dynamic routing capabilities to serve content in different formats and a dedicated API for specialized content delivery.

Sources: README.md, package.json

Core Technologies and Dependencies

The project's functionality is built upon a modern web development stack. The key dependencies defined in package.json establish the foundation for content management, rendering, and styling.

Dependency	Role
next	The core React framework for building the static and server-rendered application.
contentlayer	A content SDK that validates and transforms Markdown content into type-safe JSON data.
twin.macro	A library that blends the power of Tailwind CSS with CSS-in-JS for styling components.
meilisearch	Powers the site's search functionality by indexing the documentation content.
react	The fundamental UI library for building components.
typescript	Provides static typing to enhance code quality and developer experience.
next-seo	Manages SEO-related meta tags and structured data.

Sources: package.json

Content Management with Contentlayer

Contentlayer is central to the content pipeline. It reads Markdown files from the src/docs directory, validates their structure against a defined schema, and generates type-safe data that can be imported directly into the application's components.

Sources: contentlayer.config.ts

Document Schema

The Page document type is defined in contentlayer.config.ts. It specifies the expected fields for each Markdown file, including required frontmatter like title and description. A computed url field is also generated based on the file's path.

// contentlayer.config.ts:7-27
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:7-27

Content Processing Flow

The build process orchestrated by Contentlayer can be visualized as follows:

This diagram shows how raw Markdown files are converted into a structured allPages object, which is then used for page generation.

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

Routing and Page Rendering

The application uses a combination of static and dynamic rendering strategies, managed by Next.js's file-based routing system and custom middleware.

Static Page Generation ([...slug].tsx)

Most documentation pages are statically generated at build time for optimal performance. The src/pages/[...slug].tsx file handles this process.

1. getStaticPaths: This function reads all page URLs from the allPages object (generated by Contentlayer) and tells Next.js which paths to pre-render.
2. getStaticProps: For each path, this function finds the corresponding page data and passes it as props to the PostPage component.
3. PostPage Component: It uses the useMDXComponent hook from next-contentlayer/hooks to render the MDX content of the page.

Sources: src/pages/[...slug].tsx:67-80

Dynamic Page Rendering and Middleware

To support features like serving raw Markdown content, the project uses a combination of middleware and a dynamic page route.

Middleware (middleware.ts)

The middleware intercepts incoming requests and rewrites them based on specific criteria. Its primary functions are:

• To check if a requested path corresponds to a valid documentation page.
• To determine if the client is requesting content in Markdown format. This is detected by a .md extension, a ?format=md query parameter, or an Accept header preferring text/markdown.
• If Markdown is requested, it rewrites the URL to /dynamic/[...slug]?format=md. Otherwise, it rewrites to /dynamic/[...slug] for standard HTML rendering.

This approach avoids conflicts with Next.js's default static generation while enabling flexible content delivery.

Sources: src/middleware.ts

Request Flow for Different Content Types

The following diagram illustrates how the middleware routes requests for either HTML or raw Markdown.

Data Structures and Types

The project defines a clear set of TypeScript interfaces to model its content and navigation structure, ensuring type safety and predictability.

Sources: src/types.ts

Page and Sidebar Structure

The core data types for representing content are defined in src/types.ts. These interfaces dictate the shape of the sidebar navigation and individual pages.

• IPage: Represents a single documentation page with a title and a slug.
• ISidebarSection: A top-level section in the sidebar, which can contain pages, subsections, or external links.
• ISubSection: A nested group of pages under a subtitle.
• ISidebarContent: An array of ISidebarSection objects, representing the entire sidebar.

The relationship between these types is illustrated below.

Sidebar Content (sidebar.ts)

The actual navigation structure of the documentation site is defined in src/data/sidebar.ts. This file exports a sidebarContent constant that conforms to the ISidebarContent type, organizing all pages into a narrative structure with sections and subsections. A helper function makePage is used to create page objects with consistent slug generation.

Sources: src/data/sidebar.ts

Layout and UI

The user interface is constructed with a main layout component that provides consistent structure, navigation, and SEO features to all documentation pages.

DocsLayout.tsx

This component is the primary layout for all documentation pages. It wraps the MDX content and provides several key features:

• SEO: Integrates the SEO component to manage all meta tags and structured data.
• Page Navigation: Renders the PageNav component, which creates a "On This Page" table of contents.
• Previous/Next Links: Calculates and displays links to the previous and next documents based on the sidebar order. This is achieved using the flattenSidebarContent utility function.
• GitHub Integration: Provides an "Edit this file on GitHub" link for easy contributions.
• Copy as Markdown: A button to copy the raw Markdown of the current page to the clipboard.

Sources: src/layouts/DocsLayout.tsx

SEO.tsx

The SEO component is responsible for generating comprehensive SEO metadata. It goes beyond basic title and description tags by creating rich structured data (JSON-LD) schemas, including:

• Organization: Information about Railway.
• BreadcrumbList: A breadcrumb trail based on the page's position in the sidebar.
• Article: Detailed metadata about the documentation page itself.
• FAQPage: Automatically generated if the page contains headers that are questions (ending in "?").

This structured data helps search engines better understand and index the site's content.

Sources: src/components/SEO.tsx:40-120

API Endpoints

The project includes API routes for specialized data-serving purposes.

/api/llms-docs.md.ts

This API endpoint is designed to serve the entire documentation content as a single, consolidated Markdown file, optimized for consumption by Large Language Models (LLMs).

The process is as follows:

1. It retrieves the complete list of pages from the sidebar configuration.
2. It iterates through each page, reading the corresponding Markdown file from the src/docs directory.
3. For each file, it parses the content, extracts the title and description, and strips out complex Markdown elements like code blocks and links to create a clean, text-only version.
4. All processed content is concatenated into a single string.
5. The final string is sent as a text/plain response.