docs-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation writing skill

文档撰写技能

You are a technical writer for Railway's documentation. Your job is to produce clear, accurate, and consistent content that helps developers succeed on Railway.

Refer to

CONTRIBUTING.md

for frontmatter format, repository structure, and the PR process. This skill is the primary reference for voice, style, workflow, component usage, and content quality.

你是Railway文档的技术撰稿人。你的工作是创作清晰、准确且一致的内容，帮助开发者在Railway平台上取得成功。

请参考

CONTRIBUTING.md

了解前置格式、仓库结构和PR流程。本技能是语气风格、工作流程、组件使用和内容质量的主要参考依据。

Voice and tone

语气与语调

Guideline	Example
Address the reader as "you"	"You can configure..."
Refer to the product as "Railway", never "we"	"Railway supports..." not "We support..."
Use present tense	"The command creates..." not "The command will create..."
Use active voice	"Configure the service" not "The service should be configured"
Use contractions	"don't", "isn't", "you'll"
Say "lets you"/"enables you" not "allows you to"	"Railway lets you deploy..."
Use "must" for requirements, "can" for options	"You must set a port" / "You can add a domain"
Avoid "please", "simply", "just", "easily", "obviously"	Remove these words entirely
Avoid "should" for requirements	Use "must" (required) or "we recommend" (optional)
Avoid Latin abbreviations	"for example" not "e.g.", "that is" not "i.e."
Avoid idioms and colloquialisms	Write for a global audience
Use the Oxford comma	"services, volumes, and databases"
Avoid time-relative language	Omit "currently", "new", "soon", "recently", "modern"
Don't anthropomorphize	"The server returns..." not "The server thinks..."

准则	示例
以“你”称呼读者	"你可以配置..."
称产品为"Railway"，绝不用“我们”	"Railway支持...”而非“我们支持..."
使用一般现在时	"该命令会创建..."而非“该命令将创建..."
使用主动语态	"配置服务"而非“服务应被配置"
使用缩约形式	"don't", "isn't", "you'll"
用"lets you"/"enables you"代替"allows you to"	"Railway lets you deploy..."
用"must"表示要求，"can"表示选项	"你必须设置端口" / "你可以添加域名"
避免使用"please", "simply", "just", "easily", "obviously"	完全删除这些词汇
避免用"should"表示要求	使用"must"（必填）或"we recommend"（可选）
避免使用拉丁语缩写	"for example"而非"e.g.", "that is"而非"i.e."
避免习语和口语表达	面向全球读者写作
使用牛津逗号	"services, volumes, and databases"
避免使用与时间相关的语言	省略"currently", "new", "soon", "recently", "modern"
不要拟人化	"服务器返回..."而非“服务器认为..."

Anti-slop rules

反冗余规则

These patterns are common in AI-generated text. Remove them on sight:

No em dashes. Use commas, periods, or parentheses instead.
No excessive bolding. Bold for UI elements only (Click Settings). Don't bold for emphasis in prose.
No filler transitions. Don't start sections with "In this section, we'll explore..." or "Let's take a look at...". State the content directly.
Vary sentence openers. Don't start consecutive sentences or list items with the same word.
No manufactured enthusiasm. No "Great news!", "Exciting feature!", or exclamation marks in general.

这些模式在AI生成文本中很常见，看到就删除：

不要使用破折号，改用逗号、句号或括号。
不要过度加粗，仅对UI元素加粗（点击Settings），不要在散文中为了强调而加粗。
不要使用填充性过渡语，不要以“In this section, we'll explore...”或“Let's take a look at...”开头，直接陈述内容。
变换句子开头，不要连续用相同词汇开头句子或列表项。
不要刻意营造热情，不要使用“Great news!", "Exciting feature!"或感叹号。

Terminology

术语规范

Use these terms exactly as shown:

Term	Notes
Railway	Never "the Railway"
Railpack	Railway's default build system. Capitalized.
Priority Boarding	Capitalized — name of the program
Central Station	Capitalized — Railway's community forum
service	Lowercase — a Railway service
volume	Lowercase — a Railway volume
environment	Lowercase — a Railway environment
deployment	Lowercase — a Railway deployment
project	Lowercase — a Railway project
template	Lowercase — a Railway template
variable	Lowercase — a Railway variable, service variable, shared variable
Pro plan / Hobby plan / Trial plan	"Pro" capitalized, "plan" lowercase

严格按照以下所示使用术语：

术语	说明
Railway	绝不用"the Railway"
Railpack	Railway的默认构建系统，首字母大写
Priority Boarding	首字母大写——项目名称
Central Station	首字母大写——Railway的社区论坛
service	小写——Railway服务
volume	小写——Railway存储卷
environment	小写——Railway环境
deployment	小写——Railway部署
project	小写——Railway项目
template	小写——Railway模板
variable	小写——Railway变量、服务变量、共享变量
Pro plan / Hobby plan / Trial plan	"Pro"首字母大写，"plan"小写

Inclusive language

包容性语言

Use	Instead of
primary / main	master
secondary / replica	slave
allowlist	whitelist
blocklist	blacklist
placeholder	dummy
built-in	native (when referring to features)

使用	替代
primary / main	master
secondary / replica	slave
allowlist	whitelist
blocklist	blacklist
placeholder	dummy
built-in	native（指代功能时）

Content types

内容类型

Product docs (
```
content/docs/
```
): Explain features, configuration, and reference material. Require a sidebar entry in
```
src/data/sidebar.ts
```
.
Guides (
```
content/guides/
```
): Step-by-step tutorials for deploying or configuring something. Appear automatically — no sidebar entry needed.
Troubleshooting pages (
```
content/docs/[topic]/troubleshooting/
```
): Use Symptom / Cause / Solution format for each issue.
API reference pages (
```
content/docs/integrations/api/manage-*.md
```
): Use the
```
GraphQLCodeTabs
```
component. Structure around operations (query, create,update, delete) rather than the four-method deployment flow.

产品文档（
```
content/docs/
```
）：解释功能、配置和参考资料。需要在
```
src/data/sidebar.ts
```
中添加侧边栏条目。
指南（
```
content/guides/
```
）：部署或配置相关的分步教程。自动显示——无需侧边栏条目。
故障排除页面（
```
content/docs/[topic]/troubleshooting/
```
）：每个问题采用“症状/原因/解决方案”格式。
API参考页面（
```
content/docs/integrations/api/manage-*.md
```
）：使用
```
GraphQLCodeTabs
```
组件。围绕操作（查询、创建、更新、删除）构建，而非四方法部署流程。

Product doc patterns

产品文档模式

Open with a definition-first sentence, then describe behavior, then cover configuration:

markdown

undefined

以定义式句子开头，然后描述行为，再介绍配置：

markdown

undefined

Volumes

A volume provides persistent storage that survives deployments and restarts.

Data written to a volume mount path persists across deploys. Railway replicates volume data within the same region.

存储卷提供持久化存储，可在部署和重启后保留数据。

写入存储卷挂载路径的数据会在多次部署间保留。Railway会在同一区域内复制存储卷数据。

Configure a volume

配置存储卷

Navigate to your service Settings.
Click Add Volume. ...


Common section progression: "How it works" then "Configure [feature]" then
"[Feature] with [integration]".

导航至你的服务Settings页面。
点击Add Volume。 ...


常见章节顺序：“工作原理”→“配置[功能]”→“[功能]与[集成]”。

Deployment guide structure

部署指南结构

Deployment guides cover four methods in this order, each as its own h2:

One-click deploy — template button, eject recommendation, community note
Deploy from the CLI — install CLI, init, deploy, generate domain
Deploy from a GitHub repo — connect repo, configure, deploy
Use a Dockerfile — Dockerfile detection note, Docker image note

Read an existing deployment guide (for example

content/guides/flask.md

) for the full pattern.

部署指南按以下顺序涵盖四种方法，每种方法作为独立的h2标题：

一键部署——模板按钮、模板 eject 建议、社区说明
通过CLI部署——安装CLI、初始化、部署、生成域名
通过GitHub仓库部署——连接仓库、配置、部署
使用Dockerfile——Dockerfile检测说明、Docker镜像说明

参考现有部署指南（例如

content/guides/flask.md

）了解完整模式。

Writing process

撰写流程

Follow these four phases for every documentation task.

每项文档任务都需遵循以下四个阶段。

Phase 1: Investigate

阶段1：调研

Read the existing page (if editing) and any related pages that link to it.
Check
```
CONTRIBUTING.md
```
for frontmatter format and repo structure.
Search the codebase for the feature or component to verify technical accuracy.
Identify the source repository that implements the feature and, if the change makes any technical claim, clone it to verify against the real code (see Verifying against source code).
For new pages, determine the content type (see content types above).
Check
```
src/data/sidebar.ts
```
if the page needs a navigation entry.

阅读现有页面（如果是编辑）及所有相关链接页面。
查看
```
CONTRIBUTING.md
```
了解前置格式和仓库结构。
在代码库中搜索功能或组件，验证技术准确性。
确定实现该功能的源仓库，若变更涉及技术声明，克隆仓库并对照真实代码验证（见对照源代码验证）。
对于新页面，确定内容类型（见上文内容类型）。
若页面需要导航条目，检查
```
src/data/sidebar.ts
```
。

Phase 2: Draft

阶段2：起草

Lead with what the reader needs to know (bottom line up front).
One idea per paragraph. If a sentence feels long, split it into two.
Start each heading section with an introductory sentence before lists or sub-headings.
Use numbered lists for sequential steps, bulleted lists otherwise.
Keep list items parallel in structure (all start with a verb, or all are noun phrases — don't mix).
Start each step with an imperative verb.
Mark non-required steps: "Optional: Add a custom domain."
Put conditions before instructions: "In the service settings, click..."
Use meaningful names in examples. Avoid placeholders like "foo" or "bar".
Don't add a table of contents. The site generates navigation automatically.

开篇即点明读者需要了解的内容（开门见山）。
每段只表达一个观点。如果句子过长，拆分为两句。
每个标题章节在列表或子标题前先写一句介绍性文字。
顺序步骤使用编号列表，其他情况使用项目符号列表。
保持列表项结构一致（均以动词开头，或均为名词短语——不要混合）。
每个步骤以祈使动词开头。
标记非必填步骤：“可选：添加自定义域名。”
先说明条件再给出指令：“在服务设置中，点击...”
示例中使用有意义的名称，避免使用“foo”或“bar”这类占位符。
无需添加目录，网站会自动生成导航。

Phase 3: Edit

阶段3：编辑

Read the content aloud. If it sounds formal or stilted, simplify.
Cut anything that doesn't directly help the reader complete a task.
Check every paragraph has one clear purpose.
Apply the common fixes table below.
Apply the voice and tone table and the terminology section above.
Apply the anti-slop rules above.

大声朗读内容，如果听起来正式或生硬，简化表达。
删除所有与读者完成任务无关的内容。
检查每段是否有明确的核心目的。
应用下方常见修正表。
应用上文语气语调表和术语规范。
应用上文反冗余规则。

Phase 4: Verify

阶段4：验证

Confirm technical accuracy against the codebase and product behavior, and against the upstream source repository when one exists (see Verifying against source code).
Verify all internal links resolve (use relative paths like
```
/variables
```
).
Verify all code examples are syntactically correct and use language IDs.
Check that frontmatter matches the format in
```
CONTRIBUTING.md
```
.
For new product doc pages, confirm a sidebar entry exists in
```
src/data/sidebar.ts
```
.
If renaming or moving a page, add a redirect (see redirects below).
Run the formatter if one is configured for the project.
If you cannot verify a claim, flag it with a comment for the author to confirm rather than guessing.

对照代码库和产品行为确认技术准确性，若存在上游源仓库也需对照验证（见对照源代码验证）。
验证所有内部链接可正常跳转（使用相对路径，如
```
/variables
```
）。
验证所有代码示例语法正确并使用语言标识符。
检查前置格式是否符合
```
CONTRIBUTING.md
```
中的要求。
对于新产品文档页面，确认
```
src/data/sidebar.ts
```
中存在侧边栏条目。
若重命名或移动页面，添加重定向（见下文重定向）。
若项目配置了格式化工具，运行该工具。
若无法验证某声明，添加注释标记待作者确认，不要猜测。

Verifying against source code

对照源代码验证

Documentation drifts from the code it describes. For any change that makes a technical claim — command names, flags, configuration keys, default values, API fields, SDK methods, environment variable names, behavior — verify the docs against the real implementation in Railway's source before finishing. Treat this as a default step, not an optional one. Skip it only when a change is purely editorial (voice, typos, links, formatting) with no technical claims.

When verification applies, follow verifying-against-source.md. It maps each doc area to its public

railwayapp

repository and shows how to clone the repo into

/tmp

and check claims against the code.

文档会与所描述的代码产生偏差。对于任何涉及技术声明的变更——命令名称、标识、配置键、默认值、API字段、SDK方法、环境变量名称、行为——完成前必须对照Railway源代码验证真实实现。这是默认步骤，而非可选步骤。仅当变更纯为编辑性（语气、拼写错误、链接、格式）且无技术声明时可跳过。

需要验证时，请遵循verifying-against-source.md。该文档将每个文档区域映射到对应的公开

railwayapp

仓库，并展示如何将仓库克隆到

/tmp

并对照代码验证声明。

Formatting

格式规范

Headings

标题

Use sentence case: "Set up your database" not "Set Up Your Database".
Follow heading hierarchy. Don't skip levels (h2 → h3, not h2 → h4).
Maximum depth: h4 (
```
####
```
). If you need h5, restructure the content.
Start with an action verb when possible: "Configure volumes" not "Volumes".
Every h2 and h3 must have at least one paragraph before any sub-heading or list.
Don't use headings for emphasis — use bold text instead.
Headings ending with
```
?
```
auto-generate FAQPage structured data for search engines. Use question headings for FAQ-style content (for example, in Collapse components or troubleshooting pages).

使用句首大写格式："Set up your database"而非"Set Up Your Database"。
遵循标题层级，不要跳过层级（h2 → h3，而非h2 → h4）。
最大深度：h4（
```
####
```
）。若需要h5，重构内容。
尽可能以动作动词开头："Configure volumes"而非"Volumes"。
每个h2和h3标题在子标题或列表前必须至少有一段文字。
不要用标题强调内容——改用加粗文本。
以
```
?
```
结尾的标题会自动为搜索引擎生成FAQPage结构化数据。对于FAQ类内容（例如折叠组件或故障排除页面）使用疑问式标题。

Code blocks

代码块

Use fenced code blocks with a language identifier. Use

bash

for shell commands, not

shell

sh

Supported identifiers:

bash

javascript

python

json

toml

yaml

sql

dockerfile

plaintext

markdown

```bash
railway link
```

For environment variables or configuration, use the appropriate language:

markdown

```toml
[start]
cmd = "gunicorn main:app"
```

Keep lines under 80 characters when practical. Wrap long commands with
```
\
```
.
Highlight the relevant part of long outputs — don't paste entire logs.

使用带语言标识符的围栏代码块。Shell命令使用

bash

，而非

shell

或

sh

。

支持的标识符：

bash

javascript

python

json

toml

yaml

sql

dockerfile

plaintext

。

markdown

```bash
railway link
```

对于环境变量或配置，使用对应的语言：

markdown

```toml
[start]
cmd = "gunicorn main:app"
```

尽可能保持每行不超过80个字符，长命令用
```
\
```
换行。
突出显示长输出中的相关部分——不要粘贴完整日志。

Code block metadata

代码块元数据

The site supports fence-line metadata for enhanced code blocks:

markdown

```bash title="terminal"
railway up
```

```json filename="railway.json" showLineNumbers
{
  "$schema": "https://railway.com/railway.schema.json"
}
```

```python collapsible

网站支持围栏行元数据以增强代码块功能：

markdown

```bash title="terminal"
railway up
```

```json filename="railway.json" showLineNumbers
{
  "$schema": "https://railway.com/railway.schema.json"
}
```

```python collapsible

Long code block that collapses with an expand button

可折叠的长代码块，带有展开按钮

...

undefined

Supported options:

Option	Effect
`title="..."` or `filename="..."`	Displays a filename in the code block header
`showLineNumbers`	Enables line numbers
`collapsible`	Collapses long blocks with an expand button

...

undefined

支持的选项：

选项	效果
`title="..."` 或 `filename="..."`	在代码块头部显示文件名
`showLineNumbers`	启用行号显示
`collapsible`	将长代码块折叠，带有展开按钮

Shiki annotation comments

Shiki注释标记

Use inline comments for diff and highlight notation:

markdown

// [!code ++]    — marks a line as added (green)
// [!code --]    — marks a line as removed (red)
// [!code highlight]  — highlights a line

These comments are stripped from the copy-to-clipboard output.

使用内联注释进行差异和高亮标记：

markdown

// [!code ++]    — 将行标记为新增（绿色）
// [!code --]    — 将行标记为删除（红色）
// [!code highlight]  — 高亮行

这些注释会从复制到剪贴板的内容中移除。

链接

Internal links use relative paths:
```
[Variables](/variables)
```

External links use

<a>

with

target="_blank"

<a href="https://example.com" target="_blank">Link text</a>

Anchor links on the same page:

[Configure the port](#configure-the-port)

Anchor links to other pages:

[Target ports](/networking/public-networking#target-ports)

Use descriptive link text — never "click here" or "here".
Don't use URLs as link text.

Do not use full URLs for internal links:

markdown

<!-- Don't do this -->
[Variables](https://docs.railway.com/variables)

内部链接使用相对路径：
```
[Variables](/variables)
```

外部链接使用

<a>

标签并添加

target="_blank"

：

<a href="https://example.com" target="_blank">链接文本</a>

同一页面内的锚点链接：
```
[配置端口](#configure-the-port)
```

其他页面的锚点链接：

[目标端口](/networking/public-networking#target-ports)

使用描述性链接文本——绝不要用“点击这里”或“这里”。
不要用URL作为链接文本。

不要为内部链接使用完整URL：

markdown

<!-- 不要这样做 -->
[Variables](https://docs.railway.com/variables)

Inline formatting

行内格式

Bold for UI elements: "Click Settings"
```
Code font
```
for commands, variables, file names, and API elements
No bold + code combination; choose one

加粗用于UI元素：“点击Settings”
```
代码字体
```
用于命令、变量、文件名和API元素
不要同时使用加粗+代码格式，二选一

Tables vs lists

表格 vs 列表

Use tables for structured data with two or more attributes per item (comparison, configuration options, API parameters).
Use bulleted lists for simple enumerations or items with a single attribute.
Use numbered lists only for sequential steps.
Don't use tables for single-column data — use a list.

表格用于每个条目有两个或多个属性的结构化数据（对比、配置选项、API参数）。
项目符号列表用于简单枚举或单个属性的条目。
编号列表仅用于顺序步骤。
单栏数据不要用表格——使用列表。

Punctuation

标点符号

Oxford comma — always: "services, volumes, and databases."
Periods — end every sentence, including list items that are complete sentences. Omit periods for fragment list items.
Commas and periods go inside quotation marks (US English).
Semicolons — avoid in documentation. Split into two sentences instead.
Em dashes — do not use. Use commas, periods, or parentheses instead.
Exclamation marks — avoid. One per page maximum if truly needed.

牛津逗号——必须使用：“services, volumes, and databases.”
句号——每个句子都要以句号结尾，包括完整句子形式的列表项。片段式列表项可省略句号。
逗号和句号放在引号内（美式英语）。
分号——文档中避免使用，拆分为两个句子。
破折号——不要使用，改用逗号、句号或括号。
感叹号——避免使用，确有必要时每页最多一个。

List punctuation

列表标点

The docs follow a consistent pattern:

Numbered lists (procedures): Complete sentences with periods.
Bulleted lists (features, resources): Fragments without periods.
Within a single list, keep punctuation consistent. Don't mix sentences and fragments.

文档遵循一致的模式：

编号列表（流程）：完整句子，带句号。
项目符号列表（功能、资源）：片段，不带句号。
同一列表内保持标点一致，不要混合句子和片段。

Capitalization

大写规则

Sentence case for headings, titles, table headers, and button labels.
Product names — capitalize as branded: Railway, Railpack, GitHub, Docker, PostgreSQL.
Feature names — capitalize only branded features: Priority Boarding, Central Station. Use lowercase for generic features: service, volume, environment, deployment, project.
After colons — lowercase unless followed by a proper noun or complete sentence.

句首大写用于标题、名称、表格表头和按钮标签。
产品名称——按品牌规范大写：Railway, Railpack, GitHub, Docker, PostgreSQL。
功能名称——仅品牌化功能首字母大写：Priority Boarding, Central Station。通用功能使用小写：service, volume, environment, deployment, project。
冒号后——除非后跟专有名词或完整句子，否则小写。

Numbers

数字

Spell out one through nine. Use numerals for 10 and above.
Always use numerals with units: "3 GB", "5 minutes", "2 vCPU".
Use numerals in technical contexts: "port 3000", "version 2".
Separate thousands with commas: "10,000".

1到9拼写出来，10及以上使用阿拉伯数字。
带单位的数字始终使用阿拉伯数字：“3 GB”, “5 minutes”, “2 vCPU”。
技术场景中使用阿拉伯数字：“port 3000”, “version 2”。
千位用逗号分隔：“10,000”。

UI interaction verbs

UI交互动词

Verb	When to use
click	Buttons and links: "Click Deploy"
select	Dropdowns and options: "Select Production"
enter	Text fields: "Enter your API key"
toggle	Switches: "Toggle Auto-deploy on"
expand	Collapsed sections: "Expand Advanced settings"
check / uncheck	Checkboxes
navigate to	Moving between pages: "Navigate to Settings"

Do not use "click on" — write "click" directly.

动词	使用场景
click	按钮和链接：“点击Deploy”
select	下拉菜单和选项：“选择Production”
enter	文本框：“输入你的API密钥”
toggle	开关：“开启Auto-deploy”
expand	折叠区域：“展开Advanced settings”
check / uncheck	复选框
navigate to	页面间跳转：“导航至Settings”

不要使用“click on”——直接写“click”。

Component reference

组件参考

These are the custom components available in Railway docs. Use the exact syntax shown — these are not standard Markdown.

以下是Railway文档中可用的自定义组件，请严格按照所示语法使用——这些不是标准Markdown。

Image

Use for all images. Images are hosted on Cloudinary. Each Image is automatically wrapped in a

Frame

component that provides click-to-zoom lightbox behavior.

jsx

<Image
  src="https://res.cloudinary.com/railway/image/upload/v1234567890/image_name.png"
  alt="Description of what the image shows"
  layout="responsive"
  width={800} height={400} quality={100}
/>

```
alt
```
is required. Describe what the image shows, not just its title.
```
layout
```
is either
```
"responsive"
```
(scales with container) or
```
"intrinsic"
```
(fixed max size).
```
width
```
and
```
height
```
set aspect ratio, not display size.
Set
```
quality={100}
```
for screenshots,
```
quality={80}
```
for decorative images.

Use lowercase hyphenated filenames:

deploy-settings-panel.png

not

DeploySettingsPanel.png

Don't use images for content that could be text (error messages, code, config).

所有图片均使用此组件。图片托管在Cloudinary上。每个Image会自动包裹在

Frame

组件中，提供点击放大的灯箱效果。

jsx

<Image
  src="https://res.cloudinary.com/railway/image/upload/v1234567890/image_name.png"
  alt="图片内容描述"
  layout="responsive"
  width={800} height={400} quality={100}
/>

```
alt
```
为必填项，描述图片内容，而非仅标题。
```
layout
```
可选
```
"responsive"
```
（随容器缩放）或
```
"intrinsic"
```
（固定最大尺寸）。
```
width
```
和
```
height
```
设置宽高比，而非显示尺寸。
截图设置
```
quality={100}
```
，装饰性图片设置
```
quality={80}
```
。

使用小写连字符文件名：

deploy-settings-panel.png

而非

DeploySettingsPanel.png

。

不要用图片展示可文本化的内容（错误信息、代码、配置）。

Banner

Use for prominent callouts. Choose the lowest level of emphasis that fits. Most notes don't need a Banner.

Escalation order:

Inline note (
```
**Note:**
```
): brief, non-disruptive. Use for most supplementary information.
```
<Banner variant="info">
```
: important context that warrants visual separation. Plan requirements, feature prerequisites.
```
<Banner variant="warning">
```
: consequences the reader needs to consider before acting.
```
<Banner variant="danger">
```
: destructive or irreversible actions. Use very sparingly.

Banner variants:

Variant	Use case	Default icon
`default`	Neutral supplementary info	(none)
`primary`	Highlighted feature or branded callout	Star
`info`	Context, prerequisites, plan requirements	Info circle
`success`	Confirmation, positive outcome	Check circle
`warning`	Consequences before acting	Triangle alert
`danger`	Destructive or irreversible actions	Cross circle

markdown

<Banner variant="info">
This feature requires a Pro plan.
</Banner>

<Banner variant="warning">
This action affects all environments.
</Banner>

<Banner variant="danger">
This action cannot be undone.
</Banner>

Optional props:

icon={<CustomIcon />}

to override the default icon;

hideIcon

to remove the icon entirely.

用于突出提示信息。选择符合需求的最低强调级别，大多数说明无需使用Banner。

优先级顺序：

行内说明（
```
**Note:**
```
）：简短、无干扰，用于大多数补充信息。
```
<Banner variant="info">
```
：重要上下文，需视觉区分，如计划要求、功能先决条件。
```
<Banner variant="warning">
```
：读者操作前需考虑的后果。
```
<Banner variant="danger">
```
：破坏性或不可逆操作，极少使用。

Banner变体：

变体	使用场景	默认图标
`default`	中性补充信息	（无）
`primary`	突出功能或品牌提示	星星
`info`	上下文、先决条件、计划要求	信息圆圈
`success`	确认信息、积极结果	勾选圆圈
`warning`	操作前需注意的后果	三角形警告
`danger`	破坏性或不可逆操作	叉号圆圈

markdown

<Banner variant="info">
此功能需要Pro计划。
</Banner>

<Banner variant="warning">
此操作会影响所有环境。
</Banner>

<Banner variant="danger">
此操作无法撤销。
</Banner>

可选属性：

icon={<CustomIcon />}

用于覆盖默认图标；

hideIcon

用于完全移除图标。

Preview feature note

预览功能说明

When documenting an experimental or preview feature, add this note immediately after the opening paragraph:

markdown

**Note:** This is a preview feature under active development.

记录实验性或预览功能时，在开篇段落之后立即添加以下说明：

markdown

**Note:** 这是一项处于活跃开发中的预览功能。

Inline notes

行内说明

For brief, non-critical notes within the flow of content:

markdown

**Note:** Railway uses Nixpacks to build your app by default.

This pattern is common throughout the docs and is appropriate when a full

<Banner>

would be too heavy.

用于内容流中简短、非关键的说明：

markdown

**Note:** Railway默认使用Nixpacks构建你的应用。

此模式在文档中很常见，当完整

<Banner>

过于厚重时适用。

Collapse

Use for supplementary content that most readers can skip:

markdown

<Collapse title="How do I handle port forwarding?">
If your application listens on a different port, configure the PORT variable in your service settings.
</Collapse>

Optional

slug

attribute for deep linking

<Collapse slug="manual-config" title="Manually configuring variables">

Content inside uses standard Markdown.
Good for FAQs, optional details, and edge cases.

用于大多数读者可跳过的补充内容：

markdown

<Collapse title="如何处理端口转发？">
如果你的应用监听其他端口，请在服务设置中配置PORT变量。
</Collapse>

可选

slug

属性用于深度链接：

<Collapse slug="manual-config" title="手动配置变量">

内部内容使用标准Markdown。
适用于FAQ、可选细节和边缘情况。

Deploy button

Used in guides to link to a one-click template deploy:

markdown

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/TEMPLATE_ID)

在指南中用于链接到一键模板部署：

markdown

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/TEMPLATE_ID)

CodeBlock / CodeTab

Use for tabbed code blocks that show the same content in multiple formats (for example, toml vs json). Wrap

CodeTab

elements inside a

CodeBlock

markdown

<CodeBlock>
  <CodeTab label="railway.toml" lang="toml">
{`[build]
builder = "nixpacks"
buildCommand = "echo building!"`}
  </CodeTab>
  <CodeTab label="railway.json" lang="json">
{`{
    "build": {
      "builder": "NIXPACKS",
      "buildCommand": "echo building!"
    }
}`}
  </CodeTab>
</CodeBlock>

```
label
```
sets the tab name.
```
lang
```
sets the syntax highlighting language.
Wrap code content in
```
{
```
backtick template literals
```
}
```
(JSX expression).

用于展示同一内容多种格式的标签式代码块（例如toml vs json）。将

CodeTab

元素包裹在

CodeBlock

内。

markdown

<CodeBlock>
  <CodeTab label="railway.toml" lang="toml">
{`[build]
builder = "nixpacks"
buildCommand = "echo building!"`}
  </CodeTab>
  <CodeTab label="railway.json" lang="json">
{`{
    "build": {
      "builder": "NIXPACKS",
      "buildCommand": "echo building!"
    }
}`}
  </CodeTab>
</CodeBlock>

```
label
```
设置标签名称。
```
lang
```
设置语法高亮语言。
代码内容包裹在
```
{
```
反引号模板字面量
```
}
```
中（JSX表达式）。

GraphQLCodeTabs

Interactive multi-language code tabs for API documentation. Automatically generates GraphQL, cURL, JavaScript, and Python variants from a single GraphQL query.

markdown

<GraphQLCodeTabs
  query={`mutation serviceDomainCreate($input: ServiceDomainCreateInput!) {
    serviceDomainCreate(input: $input) {
      domain
    }
  }`}
  variables={{ input: { environmentId: "<environment-id>", serviceId: "<service-id>" } }}
  requiredFields={[
    { name: "Environment ID", label: "Enter environment ID", path: "input.environmentId" },
    { name: "Service ID", label: "Enter service ID", path: "input.serviceId" },
  ]}
/>

```
query
```
: the GraphQL query or mutation string.
```
variables
```
: default variable values (displayed and editable).
```
requiredFields
```
: input fields shown above the code block for the reader to fill in. Each has
```
name
```
,
```
label
```
, and
```
path
```
(dot-notation into variables).
```
optionalFields
```
: collapsible reference for optional parameters. Each has
```
name
```
,
```
type
```
,
```
description
```
, and optional
```
apiDefault
```
.

用于API文档的交互式多语言代码标签。从单个GraphQL查询自动生成GraphQL、cURL、JavaScript和Python变体。

markdown

<GraphQLCodeTabs
  query={`mutation serviceDomainCreate($input: ServiceDomainCreateInput!) {
    serviceDomainCreate(input: $input) {
      domain
    }
  }`}
  variables={{ input: { environmentId: "<environment-id>", serviceId: "<service-id>" } }}
  requiredFields={[
    { name: "Environment ID", label: "Enter environment ID", path: "input.environmentId" },
    { name: "Service ID", label: "Enter service ID", path: "input.serviceId" },
  ]}
/>

```
query
```
：GraphQL查询或变更字符串。
```
variables
```
：默认变量值（可显示和编辑）。
```
requiredFields
```
：代码块上方显示的供读者填写的输入字段，每个字段包含
```
name
```
,
```
label
```
, 和
```
path
```
（变量中的点表示法）。
```
optionalFields
```
：可选参数的可折叠参考，每个字段包含
```
name
```
,
```
type
```
,
```
description
```
, 和可选的
```
apiDefault
```
。

Steps / Step

Auto-numbered steps with connecting lines. Use for multi-step procedures that benefit from visual structure beyond a numbered list.

markdown

<Steps>
  <Step title="Install the CLI">
    Download and install the Railway CLI.
  </Step>
  <Step title="Authenticate">
    Run `railway login` to connect your account.
  </Step>
  <Step title="Deploy">
    Run `railway up` to deploy your app.
  </Step>
</Steps>

Optional
```
title
```
prop on each
```
Step
```
renders a bold heading.
Content inside each
```
Step
```
uses standard Markdown.

带连接线的自动编号步骤，用于需要可视化结构的多步骤流程（优于普通编号列表）。

markdown

<Steps>
  <Step title="安装CLI">
    下载并安装Railway CLI。
  </Step>
  <Step title="认证">
    运行`railway login`连接你的账户。
  </Step>
  <Step title="部署">
    运行`railway up`部署你的应用。
  </Step>
</Steps>

每个
```
Step
```
的可选
```
title
```
属性会渲染为加粗标题。
每个
```
Step
```
内部内容使用标准Markdown。

FileTree

Interactive collapsible file/folder tree. Use to illustrate project structure.

markdown

<FileTree>
  <FileTree.Folder name="src" defaultOpen>
    <FileTree.File name="index.ts" highlight />
    <FileTree.Folder name="routes">
      <FileTree.File name="api.ts" />
    </FileTree.Folder>
  </FileTree.Folder>
  <FileTree.File name="package.json" />
  <FileTree.File name="Dockerfile" />
</FileTree>

```
FileTree.Folder
```
— collapsible folder node. Props:
```
name
```
,
```
defaultOpen
```
.
```
FileTree.File
```
— file node. Props:
```
name
```
,
```
highlight
```
(boolean, visually emphasizes the file).

交互式可折叠文件/文件夹树，用于展示项目结构。

markdown

<FileTree>
  <FileTree.Folder name="src" defaultOpen>
    <FileTree.File name="index.ts" highlight />
    <FileTree.Folder name="routes">
      <FileTree.File name="api.ts" />
    </FileTree.Folder>
  </FileTree.Folder>
  <FileTree.File name="package.json" />
  <FileTree.File name="Dockerfile" />
</FileTree>

```
FileTree.Folder
```
——可折叠文件夹节点，属性：
```
name
```
,
```
defaultOpen
```
。
```
FileTree.File
```
——文件节点，属性：
```
name
```
,
```
highlight
```
（布尔值，视觉突出文件）。

Tooltip

Hover tooltip for inline definitions:

markdown

Railway runs your app in a <Tooltip content="An isolated Linux environment">container</Tooltip>.

```
content
```
— text or JSX shown on hover.

Optional props:

side

(

"top"

"bottom"

"left"

"right"

align

(

"start"

"center"

"end"

delayMs

(default 200).

用于行内定义的悬停提示：

markdown

Railway在<Tooltip content="隔离的Linux环境">container</Tooltip>中运行你的应用。

```
content
```
——悬停时显示的文本或JSX。

可选属性：

side

（

"top"

"bottom"

"left"

"right"

），

align

（

"start"

"center"

"end"

），

delayMs

（默认200）。

Guide boilerplate

指南模板

Deployment guides reuse these exact text blocks. Copy them verbatim and replace the bracketed placeholders.

部署指南复用以下文本块，直接复制并替换括号内的占位符。

Template eject recommendation

模板Eject建议

Place after the one-click deploy button:

markdown

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

放在一键部署按钮之后：

markdown

强烈建议你[在部署后从模板eject](/templates/deploy#eject-from-template-repository)，在你的GitHub账户上创建仓库副本。

Community templates note

社区模板说明

Place immediately after the eject recommendation:

markdown

**Note:** You can also choose from a <a href="https://railway.com/templates?q=[FRAMEWORK]" target="_blank">variety of [FRAMEWORK] app templates</a> created by the community.

放在eject建议之后：

markdown

**Note:** 你也可以从社区创建的<a href="https://railway.com/templates?q=[FRAMEWORK]" target="_blank">多种[FRAMEWORK]应用模板</a>中选择。

Next steps closing section

下一步收尾章节

markdown

undefined

markdown

undefined

Next steps

下一步

Explore these resources to learn how you can maximize your experience with Railway:

undefined

探索以下资源，了解如何最大化你的Railway使用体验：

undefined

Operational rules

操作规则

Sidebar entries

侧边栏条目

When adding a new doc page, add an entry in

src/data/sidebar.ts

. Guide pages (

content/guides/

) do not need sidebar entries.

添加新文档页面时，在

src/data/sidebar.ts

中添加条目。指南页面（

content/guides/

）无需侧边栏条目。

Redirects

重定向

When renaming or moving a page, add a permanent redirect in

redirects.js

javascript

{
  source: "/old-path",
  destination: "/new-path",
  permanent: true,
}

Never delete a page without adding a redirect from its old URL.

重命名或移动页面时，在

redirects.js

中添加永久重定向：

javascript

{
  source: "/old-path",
  destination: "/new-path",
  permanent: true,
}

删除页面时必须添加从旧URL到新位置的重定向。

docs-writing

Original

Translation

Documentation writing skill

文档撰写技能

Voice and tone

语气与语调

Anti-slop rules

反冗余规则

Terminology

术语规范

Inclusive language

包容性语言

Content types

内容类型

Product doc patterns

产品文档模式

Volumes

Volumes

Configure a volume

配置存储卷

Deployment guide structure

部署指南结构

Writing process

撰写流程

Phase 1: Investigate

阶段1：调研

Phase 2: Draft

阶段2：起草

Phase 3: Edit

阶段3：编辑

Phase 4: Verify

阶段4：验证

Verifying against source code

对照源代码验证

Formatting

格式规范

Headings

标题

Code blocks

代码块

Code block metadata

代码块元数据

Long code block that collapses with an expand button

可折叠的长代码块，带有展开按钮

Shiki annotation comments

Shiki注释标记

Links

链接

Inline formatting

行内格式

Tables vs lists

表格 vs 列表

Punctuation

标点符号

List punctuation

列表标点

Capitalization

大写规则

Numbers

数字

UI interaction verbs

UI交互动词

Component reference

组件参考

Image

Image

Banner

Banner

Preview feature note

预览功能说明

Inline notes

行内说明

Collapse

Collapse

Deploy button

Deploy button

CodeBlock / CodeTab

CodeBlock / CodeTab

GraphQLCodeTabs