API Endpoint: Export

Relevant source files

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

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

The Railway documentation project provides two primary mechanisms for exporting its content in machine-readable formats. The main export endpoint is designed for Large Language Model (LLM) consumption, aggregating all documentation pages into a single, structured plain text file. This is handled by the /api/llms-docs.md API route.

A secondary mechanism allows for the export of individual documentation pages in their raw Markdown format. This is achieved by appending a query parameter (?format=md) to a page's URL or by using an appropriate Accept header. A middleware intercepts these requests and serves the raw markdown content.

LLM Documentation Export (/api/llms-docs.md)

This API endpoint generates a single, comprehensive text/plain file containing the entire documentation content, specifically formatted for consumption by LLMs. It traverses the documentation structure, reads each page, cleans the content, and concatenates it into one file.

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

Data Flow

The process begins when a request hits the /api/llms-docs.md endpoint. The handler then executes a series of steps to build the final text file.

The following diagram illustrates the data flow for generating the LLM documentation export.

Core Logic

1. Initialization: The API handler sets the response header Content-Type to text/plain.
   Sources: src/pages/api/llms-docs.md.ts:9

2. Page Collection: It retrieves the entire documentation structure from sidebarContent and uses the flattenSidebarContent utility function to create a flat list of all page objects (IPage).
   Sources: src/pages/api/llms-docs.md.ts:12, src/layouts/DocsLayout.tsx:38-61, src/data/sidebar.ts

3. Content Aggregation: The handler iterates through each page, reads the corresponding markdown file from src/docs/, and parses it using gray-matter to separate the frontmatter from the main content.
   Sources: src/pages/api/llms-docs.md.ts:63-66

4. Content Cleaning: For each page, the markdown content is processed to make it more suitable for an LLM. This involves:

   • Removing code blocks (```).
   • Removing inline code backticks.
   • Replacing markdown links with just their text content ([text](https://github.com/Alonso-pixel/railways-docs/blob/HEAD/url) becomes text).
   • The cleaned text, along with the page title, source URL, and description from the frontmatter, is appended to the final content string.
     Sources: src/pages/api/llms-docs.md.ts:88-121

5. Code Example Extraction: After processing the main text, it separately extracts all code blocks and appends them under a "Code Examples" heading for that page.
   Sources: src/pages/api/llms-docs.md.ts:124-135

6. Response: Once all pages are processed, the complete aggregated string is sent as the response with a 200 status code.
   Sources: src/pages/api/llms-docs.md.ts:153

Individual Page Markdown Export

The system also supports exporting individual documentation pages as raw markdown. This is not a dedicated API endpoint but rather a feature of the dynamic page rendering system, enabled by a middleware.

Request Flow and Middleware

A request for a markdown version of a page can be initiated in three ways:

1. Appending .md to the page URL (e.g., /guides/projects.md).
2. Adding the ?format=md query parameter.
3. Sending a request with an Accept header that prioritizes text/markdown or text/plain over text/html.

The middleware function intercepts all incoming requests. It checks if the request matches one of the conditions for wanting markdown. If so, it rewrites the URL to point to the internal dynamic rendering path (/dynamic/...) while adding format=md as a query parameter.

Sources: src/middleware.ts

The following sequence diagram shows how the middleware and page handler interact to serve a markdown file.

Page-Level Handler

The getServerSideProps function in src/pages/dynamic/[...slug].tsx handles the server-side rendering for dynamic pages. It contains specific logic to handle markdown export requests.

If the context.query.format is md, the function:

1. Finds the requested page from allPages (provided by Contentlayer).
2. Uses reconstructMarkdownWithFrontmatter to combine the frontmatter (title, description) with the raw markdown body.
3. Sets the response Content-Type header to text/markdown; charset=utf-8.
4. Writes the reconstructed markdown content directly to the response stream and ends the request, bypassing the regular React component rendering.

Sources: src/pages/dynamic/[...slug].tsx:81-91

Key Components and Data Structures

The export functionality relies on several key components and data structures defined across the application.

Component / Type	File	Description
handler	src/pages/api/llms-docs.md.ts	The Next.js API route handler that orchestrates the generation of the full documentation export for LLMs.
getServerSideProps	src/pages/dynamic/[...slug].tsx	The server-side function that handles page rendering and contains the logic for exporting a single page as raw markdown.
middleware	src/middleware.ts	Intercepts requests and rewrites URLs to trigger the markdown export functionality based on path, query parameters, or headers.
flattenSidebarContent	src/layouts/DocsLayout.tsx	A utility function that takes the nested sidebarContent object and returns a flat array of IPage objects.
sidebarContent	src/data/sidebar.ts	A constant that defines the entire navigation and structure of the documentation site. It is the source of truth for page discovery.
IPage	src/types.ts	A TypeScript interface defining the shape of a page object, including title, slug, and description.
Page (Document Type)	contentlayer.config.ts	The Contentlayer document type definition for a documentation page, specifying the fields (title, description) extracted from markdown files.

Sources: src/pages/api/llms-docs.md.ts:8, src/pages/dynamic/[...slug].tsx:74, src/middleware.ts:19, src/layouts/DocsLayout.tsx:38, src/data/sidebar.ts:12, src/types.ts:10, contentlayer.config.ts:6