docs-writer-blog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blog Post Writer

博客文章撰写指南

Persona

角色设定

Voice: Official React team voice Tone: Accurate, professional, forward-looking

语气： 官方React团队语气 语调： 准确、专业、具有前瞻性

Voice & Style

语气与风格

For tone, capitalization, jargon, and prose patterns, invoke

/docs-voice

关于语调、大小写、专业术语和行文风格，请参考

/docs-voice

。

Frontmatter Schema

前置元数据（Frontmatter）规范

All blog posts use this YAML frontmatter structure:

yaml

---
title: "Title in Quotes"
author: Author Name(s)
date: YYYY/MM/DD
description: One or two sentence summary.
---

所有博客文章需遵循以下YAML前置元数据结构：

yaml

---
title: "Title in Quotes"
author: Author Name(s)
date: YYYY/MM/DD
description: One or two sentence summary.
---

Field Details

字段详情

Field	Format	Example
`title`	Quoted string	`"React v19"` , `"React Conf 2024 Recap"`
`author`	Unquoted, comma + "and" for multiple	`The React Team` , `Dan Abramov and Lauren Tan`
`date`	`YYYY/MM/DD` with forward slashes	`2024/12/05`
`description`	1-2 sentences, often mirrors intro	Summarizes announcement or content

字段	格式	示例
`title`	带双引号的字符串	`"React v19"` , `"React Conf 2024 Recap"`
`author`	无引号，多位作者用逗号加"and"分隔	`The React Team` , `Dan Abramov and Lauren Tan`
`date`	斜杠分隔的 `YYYY/MM/DD` 格式	`2024/12/05`
`description`	1-2句话，通常与引言内容呼应	概述公告或文章核心内容

Title Patterns by Post Type

按文章类型划分的标题格式

Type	Pattern	Example
Release	`"React vX.Y"` or `"React X.Y"`	`"React v19"`
Upgrade	`"React [VERSION] Upgrade Guide"`	`"How to Upgrade to React 18"`
Labs	`"React Labs: [Topic] – [Month Year]"`	`"React Labs: What We've Been Working On – February 2024"`
Conf	`"React Conf [YEAR] Recap"`	`"React Conf 2024 Recap"`
Feature	`"Introducing [Feature]"` or descriptive	`"Introducing react.dev"`
Security	`"[Severity] Security Vulnerability in [Component]"`	`"Critical Security Vulnerability in React Server Components"`

类型	格式	示例
版本发布	`"React vX.Y"` 或 `"React X.Y"`	`"React v19"`
升级指南	`"React [VERSION] Upgrade Guide"`	`"How to Upgrade to React 18"`
实验室研究	`"React Labs: [Topic] – [Month Year]"`	`"React Labs: What We've Been Working On – February 2024"`
大会回顾	`"React Conf [YEAR] Recap"`	`"React Conf 2024 Recap"`
功能/工具发布	`"Introducing [Feature]"` 或描述性标题	`"Introducing react.dev"`
安全公告	`"[Severity] Security Vulnerability in [Component]"`	`"Critical Security Vulnerability in React Server Components"`

Author Byline

作者署名栏

Immediately after frontmatter, add a byline:

markdown

---

Month DD, YYYY by [Author Name](social-link)

---

前置元数据之后，需添加作者署名栏：

markdown

---

Month DD, YYYY by [Author Name](social-link)

---

Conventions

规范

Full date spelled out:
```
December 05, 2024
```

Team posts link to

/community/team

[The React Team](/community/team)

Individual authors link to Twitter/X or Bluesky
Multiple authors: Oxford comma before "and"
Followed by horizontal rule
```
---
```

Examples:

markdown

December 05, 2024 by [The React Team](/community/team)

---

markdown

May 3, 2023 by [Dan Abramov](https://bsky.app/profile/danabra.mov), [Sophie Alpert](https://twitter.com/sophiebits), and [Andrew Clark](https://twitter.com/acdlite)

---

日期需完整拼写：
```
December 05, 2024
```

团队文章链接至

/community/team

：

[The React Team](/community/team)

个人作者链接至Twitter/X或Bluesky
多位作者：在"and"前使用牛津逗号
署名栏后需添加水平分隔线
```
---
```

示例：

markdown

December 05, 2024 by [The React Team](/community/team)

---

markdown

May 3, 2023 by [Dan Abramov](https://bsky.app/profile/danabra.mov), [Sophie Alpert](https://twitter.com/sophiebits), and [Andrew Clark](https://twitter.com/acdlite)

---

Universal Post Structure

通用文章结构

All blog posts follow this structure:

Frontmatter (YAML)
Author byline with date
Horizontal rule (
```
---
```
)
<Intro>
component (1-3 sentences)
Horizontal rule (
```
---
```
) (optional)
Main content sections (H2 with IDs)
Closing section (Changelog, Thanks, etc.)

所有博客文章需遵循以下结构：

前置元数据（YAML格式）
带日期的作者署名栏
水平分隔线 (
```
---
```
)
<Intro>
组件（1-3句话）
水平分隔线 (
```
---
```
)（可选）
主要内容章节（带ID的H2标题）
收尾章节（更新日志、致谢等）

Post Type Templates

按文章类型划分的模板

Major Release Announcement

重大版本发布公告

markdown

---
title: "React vX.Y"
author: The React Team
date: YYYY/MM/DD
description: React X.Y is now available on npm! In this post, we'll give an overview of the new features.
---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

React vX.Y is now available on npm!

</Intro>

In our [Upgrade Guide](/blog/YYYY/MM/DD/react-xy-upgrade-guide), we shared step-by-step instructions for upgrading. In this post, we'll give an overview of what's new.

- [What's new in React X.Y](#whats-new)
- [Improvements](#improvements)
- [How to upgrade](#how-to-upgrade)

---

markdown

---
title: "React vX.Y"
author: The React Team
date: YYYY/MM/DD
description: React X.Y is now available on npm! In this post, we'll give an overview of the new features.
---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

React vX.Y is now available on npm!

</Intro>

In our [Upgrade Guide](/blog/YYYY/MM/DD/react-xy-upgrade-guide), we shared step-by-step instructions for upgrading. In this post, we'll give an overview of what's new.

- [What's new in React X.Y](#whats-new)
- [Improvements](#improvements)
- [How to upgrade](#how-to-upgrade)

---

What's new in React X.Y {/whats-new/}

Feature Name {/feature-name/}

[Problem this solves. Before/after code examples.]

For more information, see the docs for

Feature

[Problem this solves. Before/after code examples.]

For more information, see the docs for

Feature

Improvements in React X.Y {/improvements/}

Improvement Name {/improvement-name/}

[Description of improvement.]

How to upgrade {/how-to-upgrade/}

See How to Upgrade to React X.Y for step-by-step instructions.

Changelog {/changelog/}

React {/react/}

Add
```
useNewHook
```
for [purpose]. (#12345 by @contributor)

Thanks to Name for reviewing this post.

undefined

Add
```
useNewHook
```
for [purpose]. (#12345 by @contributor)

Thanks to Name for reviewing this post.

undefined

Upgrade Guide

升级指南

markdown

---
title: "React [VERSION] Upgrade Guide"
author: Author Name
date: YYYY/MM/DD
description: Step-by-step instructions for upgrading to React [VERSION].
---

Month DD, YYYY by [Author Name](social-url)

---

<Intro>

[Summary of upgrade and what this guide covers.]

</Intro>

<Note>

markdown

---
title: "React [VERSION] Upgrade Guide"
author: Author Name
date: YYYY/MM/DD
description: Step-by-step instructions for upgrading to React [VERSION].
---

Month DD, YYYY by [Author Name](social-url)

---

<Intro>

[Summary of upgrade and what this guide covers.]

</Intro>

<Note>

Stepping stone version {/stepping-stone/}

[If applicable, describe intermediate upgrade steps.]

</Note>

In this post, we will guide you through the steps for upgrading:

Installing
Codemods
Breaking changes
New deprecations

[If applicable, describe intermediate upgrade steps.]

</Note>

In this post, we will guide you through the steps for upgrading:

Installing
Codemods
Breaking changes
New deprecations

Installing {/installing/}

bash

npm install --save-exact react@^X.Y.Z react-dom@^X.Y.Z

bash

npm install --save-exact react@^X.Y.Z react-dom@^X.Y.Z

Codemods {/codemods/}

<Note>

Run all React [VERSION] codemods {/run-all-codemods/}

bash

npx codemod@latest react/[VERSION]/migration-recipe

</Note>

bash

npx codemod@latest react/[VERSION]/migration-recipe

</Note>

Breaking changes {/breaking-changes/}

Removed:

apiName

{/removed-api-name/}

Removed:

apiName

{/removed-api-name/}

apiName

was deprecated in Month YYYY (vX.X.X).

// Before
[old code]

// After
[new code]

<Note>

Codemod [description]:

bash

npx codemod@latest react/[VERSION]/codemod-name

</Note>

apiName

was deprecated in Month YYYY (vX.X.X).

// Before
[old code]

// After
[new code]

<Note>

Codemod [description]:

bash

npx codemod@latest react/[VERSION]/codemod-name

</Note>

New deprecations {/new-deprecations/}

Deprecated:

apiName

{/deprecated-api-name/}

Deprecated:

apiName

{/deprecated-api-name/}

[Explanation and migration path.]

Thanks to Contributor for reviewing this post.

undefined

[Explanation and migration path.]

Thanks to Contributor for reviewing this post.

undefined

React Labs Research Update

React实验室研究更新

markdown

---
title: "React Labs: What We've Been Working On – [Month Year]"
author: Author1, Author2, and Author3
date: YYYY/MM/DD
description: In React Labs posts, we write about projects in active research and development.
---

Month DD, YYYY by [Author1](url), [Author2](url), and [Author3](url)

---

<Intro>

In React Labs posts, we write about projects in active research and development. We've made significant progress since our [last update](/blog/previous-labs-post), and we'd like to share our progress.

</Intro>

[Optional: Roadmap disclaimer about timelines]

---

markdown

---
title: "React Labs: What We've Been Working On – [Month Year]"
author: Author1, Author2, and Author3
date: YYYY/MM/DD
description: In React Labs posts, we write about projects in active research and development.
---

Month DD, YYYY by [Author1](url), [Author2](url), and [Author3](url)

---

<Intro>

In React Labs posts, we write about projects in active research and development. We've made significant progress since our [last update](/blog/previous-labs-post), and we'd like to share our progress.

</Intro>

[Optional: Roadmap disclaimer about timelines]

---

Feature Name {/feature-name/}

<Note>

<FeatureName />

is now available in React's Canary channel.

</Note>

[Description of feature, motivation, current status.]

<Note>

<FeatureName />

is now available in React's Canary channel.

</Note>

[Description of feature, motivation, current status.]

Subsection {/subsection/}

[Details, examples, use cases.]

Research Area {/research-area/}

[Problem space description. Status communication.]

This research is still early. We'll share more when we're further along.

Thanks to Reviewer for reviewing this post.

Thanks for reading, and see you in the next update!

undefined

[Problem space description. Status communication.]

This research is still early. We'll share more when we're further along.

Thanks to Reviewer for reviewing this post.

Thanks for reading, and see you in the next update!

undefined

React Conf Recap

React大会回顾

markdown

---
title: "React Conf [YEAR] Recap"
author: Author1 and Author2
date: YYYY/MM/DD
description: Last week we hosted React Conf [YEAR]. In this post, we'll summarize the talks and announcements.
---

Month DD, YYYY by [Author1](url) and [Author2](url)

---

<Intro>

Last week we hosted React Conf [YEAR] [where we announced [key announcements]].

</Intro>

---

The entire [day 1](youtube-url) and [day 2](youtube-url) streams are available online.

markdown

---
title: "React Conf [YEAR] Recap"
author: Author1 and Author2
date: YYYY/MM/DD
description: Last week we hosted React Conf [YEAR]. In this post, we'll summarize the talks and announcements.
---

Month DD, YYYY by [Author1](url) and [Author2](url)

---

<Intro>

Last week we hosted React Conf [YEAR] [where we announced [key announcements]].

</Intro>

---

The entire [day 1](youtube-url) and [day 2](youtube-url) streams are available online.

Day 1 {/day-1/}

Watch the full day 1 stream here.

[Description of day 1 opening and keynote highlights.]

Watch the full day 1 keynote here:

Watch the full day 1 stream here.

[Description of day 1 opening and keynote highlights.]

Watch the full day 1 keynote here:

Day 2 {/day-2/}

Watch the full day 2 stream here.

[Day 2 summary.]

Watch the full day 2 stream here.

[Day 2 summary.]

Q&A {/q-and-a/}

Q&A Title hosted by Host

Q&A Title hosted by Host

And more... {/and-more/}

We also heard talks including:

Talk Title by Speaker

We also heard talks including:

Talk Title by Speaker

Thank you {/thank-you/}

Thank you to all the staff, speakers, and participants who made React Conf [YEAR] possible.

See you next time!

undefined

Thank you to all the staff, speakers, and participants who made React Conf [YEAR] possible.

See you next time!

undefined

Feature/Tool Announcement

功能/工具发布公告

markdown

---
title: "Introducing [Feature Name]"
author: Author Name
date: YYYY/MM/DD
description: Today we are announcing [feature]. In this post, we'll explain [what this post covers].
---

Month DD, YYYY by [Author Name](url)

---

<Intro>

Today we are [excited/thrilled] to announce [feature]. [What this means for users.]

</Intro>

---

markdown

---
title: "Introducing [Feature Name]"
author: Author Name
date: YYYY/MM/DD
description: Today we are announcing [feature]. In this post, we'll explain [what this post covers].
---

Month DD, YYYY by [Author Name](url)

---

<Intro>

Today we are [excited/thrilled] to announce [feature]. [What this means for users.]

</Intro>

---

tl;dr {/tldr/}

Key announcement point with relevant link.
What users can do now.
Availability or adoption information.

Key announcement point with relevant link.
What users can do now.
Availability or adoption information.

What is [Feature]? {/what-is-feature/}

[Explanation of the feature/tool.]

Why we built this {/why-we-built-this/}

[Motivation, history, problem being solved.]

Getting started {/getting-started/}

To install [feature]:

<TerminalBlock> npm install package-name </TerminalBlock>

You can find more documentation here.

To install [feature]:

<TerminalBlock> npm install package-name </TerminalBlock>

You can find more documentation here.

What's next {/whats-next/}

[Future plans and next steps.]

Thank you {/thank-you/}

[Acknowledgments to contributors.]

Thanks to Reviewer for reviewing this post.

undefined

[Acknowledgments to contributors.]

Thanks to Reviewer for reviewing this post.

undefined

Security Announcement

安全公告

markdown

---
title: "[Severity] Security Vulnerability in [Component]"
author: The React Team
date: YYYY/MM/DD
description: Brief summary of the vulnerability. A fix has been published. We recommend upgrading immediately.

---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

[One or two sentences summarizing the vulnerability.]

We recommend upgrading immediately.

</Intro>

---

On [date], [researcher] reported a security vulnerability that allows [description].

This vulnerability was disclosed as [CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN) and is rated CVSS [score].

The vulnerability is present in versions [list] of:

* [package-name](https://www.npmjs.com/package/package-name)

markdown

---
title: "[Severity] Security Vulnerability in [Component]"
author: The React Team
date: YYYY/MM/DD
description: Brief summary of the vulnerability. A fix has been published. We recommend upgrading immediately.

---

Month DD, YYYY by [The React Team](/community/team)

---

<Intro>

[One or two sentences summarizing the vulnerability.]

We recommend upgrading immediately.

</Intro>

---

On [date], [researcher] reported a security vulnerability that allows [description].

This vulnerability was disclosed as [CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN) and is rated CVSS [score].

The vulnerability is present in versions [list] of:

* [package-name](https://www.npmjs.com/package/package-name)

Immediate Action Required {/immediate-action-required/}

A fix was introduced in versions [linked versions]. Upgrade immediately.

Affected frameworks {/affected-frameworks/}

[List of affected frameworks with npm links.]

Vulnerability overview {/vulnerability-overview/}

[Technical explanation of the vulnerability.]

Update Instructions {/update-instructions/}

Framework Name {/update-framework-name/}

bash

npm install package@version

bash

npm install package@version

Timeline {/timeline/}

November 29th: [Researcher] reported the vulnerability.
December 1st: Fix was created and validated.
December 3rd: Fix published and CVE disclosed.

November 29th: [Researcher] reported the vulnerability.
December 1st: Fix was created and validated.
December 3rd: Fix published and CVE disclosed.

Attribution {/attribution/}

Thank you to Researcher Name for discovering and reporting this vulnerability.

---

Thank you to Researcher Name for discovering and reporting this vulnerability.

---

Heading Conventions

标题规范

ID Syntax

ID语法

All headings require IDs using CSS comment syntax:

markdown

undefined

所有标题需使用CSS注释语法添加ID：

markdown

undefined

Heading Text {/heading-id/}

undefined

undefined

ID Rules

ID规则

Lowercase
Kebab-case (hyphens for spaces)
Remove special characters (apostrophes, colons, backticks)
Concise but descriptive

小写字母
短横线分隔（Kebab-case，空格替换为短横线）
移除特殊字符（撇号、冒号、反引号）
简洁且具有描述性

Heading Patterns

标题格式示例

Context	Example
Feature section	`## New Feature: Automatic Batching {/new-feature-automatic-batching/}`
New hook	`### New hook: \` useActionState` {/new-hook-useactionstate/}`
API in backticks	`### \` <Activity />` {/activity/}`
Removed API	`#### Removed: \` propTypes` {/removed-proptypes/}`
tl;dr section	`## tl;dr {/tldr/}`

场景	示例
功能章节	`## New Feature: Automatic Batching {/new-feature-automatic-batching/}`
新Hook	`### New hook: \` useActionState` {/new-hook-useactionstate/}`
带反引号的API	`### \` <Activity />` {/activity/}`
移除的API	`#### Removed: \` propTypes` {/removed-proptypes/}`
tl;dr章节	`## tl;dr {/tldr/}`

Component Usage Guide

组件使用指南

Blog-Appropriate Components

适用于博客的组件

Component	Usage in Blog
`<Intro>`	Required - Opening summary after byline
`<Note>`	Callouts, caveats, important clarifications
`<Pitfall>`	Warnings about common mistakes
`<DeepDive>`	Optional technical deep dives (use sparingly)
`<TerminalBlock>`	CLI/installation commands
`<ConsoleBlock>`	Console error/warning output
`<ConsoleBlockMulti>`	Multi-line console output
`<YouTubeIframe>`	Conference video embeds
`<Diagram>`	Visual explanations
`<InlineToc />`	Auto-generated table of contents

组件	博客中的使用场景
`<Intro>`	必填 - 署名栏后的开篇摘要
`<Note>`	提示、注意事项、重要说明
`<Pitfall>`	常见错误警告
`<DeepDive>`	可选的技术深度解析（谨慎使用）
`<TerminalBlock>`	CLI/安装命令
`<ConsoleBlock>`	控制台错误/警告输出
`<ConsoleBlockMulti>`	多行控制台输出
`<YouTubeIframe>`	大会视频嵌入
`<Diagram>`	可视化说明
`<InlineToc />`	自动生成的目录

<Intro>

Pattern

<Intro>

组件格式

Always wrap opening paragraph:

markdown

<Intro>

React 19 is now available on npm!

</Intro>

开篇段落需始终使用

<Intro>

包裹：

markdown

<Intro>

React 19 is now available on npm!

</Intro>

<Note>

Patterns

<Note>

组件格式

Simple note:

markdown

<Note>

For React Native users, React 18 ships with the New Architecture.

</Note>

Titled note (H4 inside):

markdown

<Note>

简单提示：

markdown

<Note>

For React Native users, React 18 ships with the New Architecture.

</Note>

带标题的提示（内部包含H4）：

markdown

<Note>

React 18.3 has also been published {/react-18-3/}

To help with the upgrade, we've published

react@18.3

...

</Note> ```

To help with the upgrade, we've published

react@18.3

...

</Note> ```

<TerminalBlock>

Pattern

<TerminalBlock>

组件格式

markdown

<TerminalBlock>
npm install react@latest react-dom@latest
</TerminalBlock>

markdown

<TerminalBlock>
npm install react@latest react-dom@latest
</TerminalBlock>

<YouTubeIframe>

Pattern

<YouTubeIframe>

组件格式

markdown

<YouTubeIframe src="https://www.youtube.com/embed/VIDEO_ID" />

markdown

<YouTubeIframe src="https://www.youtube.com/embed/VIDEO_ID" />

Link Patterns

链接格式

Internal Links

内部链接

Type	Pattern	Example
Blog post	`/blog/YYYY/MM/DD/slug`	`/blog/2024/12/05/react-19`
API reference	`/reference/react/HookName`	`/reference/react/useState`
Learn section	`/learn/topic-name`	`/learn/react-compiler`
Community	`/community/team`	`/community/team`

类型	格式	示例
博客文章	`/blog/YYYY/MM/DD/slug`	`/blog/2024/12/05/react-19`
API参考文档	`/reference/react/HookName`	`/reference/react/useState`
学习板块	`/learn/topic-name`	`/learn/react-compiler`
社区板块	`/community/team`	`/community/team`

External Links

外部链接

Type	Pattern
GitHub PR	`[#12345](https://github.com/facebook/react/pull/12345)`
GitHub user	`[@username](https://github.com/username)`
Twitter/X	`[@username](https://x.com/username)`
Bluesky	`[Name](https://bsky.app/profile/handle)`
CVE	`[CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN)`
npm package	`[package](https://www.npmjs.com/package/package)`

类型	格式
GitHub PR	`[#12345](https://github.com/facebook/react/pull/12345)`
GitHub用户	`[@username](https://github.com/username)`
Twitter/X	`[@username](https://x.com/username)`
Bluesky	`[Name](https://bsky.app/profile/handle)`
CVE编号	`[CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN)`
npm包	`[package](https://www.npmjs.com/package/package)`

"See docs" Pattern

“查看文档”格式

markdown

For more information, see the docs for [`useActionState`](/reference/react/useActionState).

markdown

For more information, see the docs for [`useActionState`](/reference/react/useActionState).

Changelog Format

更新日志格式

Bullet Pattern

项目符号格式

markdown

* Add `useTransition` for concurrent rendering. ([#10426](https://github.com/facebook/react/pull/10426) by [@acdlite](https://github.com/acdlite))
* Fix `useReducer` observing incorrect props. ([#22445](https://github.com/facebook/react/pull/22445) by [@josephsavona](https://github.com/josephsavona))

Structure:

Verb

+ backticked API + description +

([#PR](url) by [@user](url))

Verbs: Add, Fix, Remove, Make, Improve, Allow, Deprecate

markdown

* Add `useTransition` for concurrent rendering. ([#10426](https://github.com/facebook/react/pull/10426) by [@acdlite](https://github.com/acdlite))
* Fix `useReducer` observing incorrect props. ([#22445](https://github.com/facebook/react/pull/22445) by [@josephsavona](https://github.com/josephsavona))

结构：

动词

+ 带反引号的API + 描述 +

([#PR编号](链接) by [@用户名](链接))

常用动词： Add、Fix、Remove、Make、Improve、Allow、Deprecate

Section Organization

章节组织方式

markdown

undefined

markdown

undefined

Changelog {/changelog/}

React {/react/}

[changes]

[更新内容]

React DOM {/react-dom/}

[changes]

---

[更新内容]

---

Acknowledgments Format

致谢格式

Post-closing Thanks

文章末尾的致谢

markdown

---

Thanks to [Name](url), [Name](url), and [Name](url) for reviewing this post.

Or italicized:

markdown

_Thanks to [Name](url) for reviewing this post._

markdown

---

Thanks to [Name](url), [Name](url), and [Name](url) for reviewing this post.

或使用斜体：

markdown

_Thanks to [Name](url) for reviewing this post._

Update Notes

更新说明

For post-publication updates:

markdown

<Note>

[Updated content]

-----

_Updated January 26, 2026._

</Note>

文章发布后的更新需添加：

markdown

<Note>

[更新内容]

-----

_Updated January 26, 2026._

</Note>

Tone & Length by Post Type

按文章类型划分的语调和篇幅

Type	Tone	Length	Key Elements
Release	Celebratory, informative	Medium-long	Feature overview, upgrade link, changelog
Upgrade	Instructional, precise	Long	Step-by-step, codemods, breaking changes
Labs	Transparent, exploratory	Medium	Status updates, roadmap disclaimers
Conf	Enthusiastic, community-focused	Medium	YouTube embeds, speaker credits
Feature	Excited, explanatory	Medium	tl;dr, "why", getting started
Security	Urgent, factual	Short-medium	Immediate action, timeline, CVE

类型	语调	篇幅	核心要素
版本发布	喜悦、信息丰富	中长	功能概述、升级指南链接、更新日志
升级指南	指导性、精准	长	分步说明、Codemods、破坏性变更
实验室研究	透明、探索性	中	状态更新、时间线免责声明
大会回顾	热情、社区导向	中	YouTube嵌入视频、讲者致谢
功能/工具发布	兴奋、解释性	中	tl;dr、“开发背景”、快速开始
安全公告	紧急、事实性	中短	立即升级提示、时间线、CVE信息

Do's and Don'ts

注意事项

Do:

Focus on facts over marketing
Say "upcoming" explicitly for unreleased features
Include FAQ sections for major announcements
Credit contributors and link to GitHub
Use "we" voice for team posts
Link to upgrade guides from release posts
Include table of contents for long posts
End with acknowledgments

Don't:

Promise features not yet available
Rewrite history (add update notes instead)
Break existing URLs
Use hyperbolic language ("revolutionary", "game-changing")
Skip the
```
<Intro>
```
component
Forget heading IDs
Use heavy component nesting in blogs
Make time estimates or predictions

需遵守：

优先陈述事实，避免营销话术
未发布的功能需明确标注“即将推出”
重大公告需包含FAQ章节
感谢贡献者并链接至GitHub
团队文章使用“我们”的语气
版本发布文章需链接至升级指南
长文章需包含目录
文章末尾添加致谢

需避免：

承诺尚未可用的功能
改写历史（如需更新，添加更新说明）
破坏现有URL
使用夸张语言（如“革命性的”、“改变游戏规则的”）
省略
```
<Intro>
```
组件
忘记添加标题ID
博客中过度嵌套组件
做出时间预估或预测

Updating Old Posts

旧文章更新规范

Never break existing URLs; add redirects when URLs change

Don't rewrite history; add update notes instead:

markdown

<Note>

[Updated information]

-----

_Updated Month Year._

</Note>

切勿破坏现有URL；URL变更时需添加重定向

切勿改写历史；如需更新，添加更新说明：

markdown

<Note>

[更新信息]

-----

_Updated Month Year._

</Note>

Critical Rules

核心规则

Heading IDs required:
```
## Title {/*title-id*/}
```
<Intro>
required: Every post starts with
```
<Intro>
```
component
Byline required: Date + linked author(s) after frontmatter
Date format: Frontmatter uses
```
YYYY/MM/DD
```
, byline uses
```
Month DD, YYYY
```
Link to docs: New APIs must link to reference documentation
Security posts: Always include "We recommend upgrading immediately"

标题ID必填：
```
## Title {/*title-id*/}
```
<Intro>
必填：所有文章需以
```
<Intro>
```
组件开篇
署名栏必填： 前置元数据后需添加带日期的作者署名
日期格式： 前置元数据使用
```
YYYY/MM/DD
```
，署名栏使用
```
Month DD, YYYY
```
链接至文档： 新API必须链接至参考文档
安全公告： 必须包含“We recommend upgrading immediately”

Components Reference

组件参考

For complete MDX component patterns, invoke

/docs-components

Blog posts commonly use:

<Intro>

<Note>

<Pitfall>

<TerminalBlock>

<ConsoleBlock>

<YouTubeIframe>

<DeepDive>

<Diagram>

Prefer inline explanations over heavy component usage.

如需完整的MDX组件格式，请调用

/docs-components

。

博客常用组件：

<Intro>

、

<Note>

、

<Pitfall>

、

<TerminalBlock>

、

<ConsoleBlock>

、

<YouTubeIframe>

、

<DeepDive>

、

<Diagram>

。

优先使用内联说明，避免过度使用组件。

docs-writer-blog

Original

Translation

Blog Post Writer

博客文章撰写指南

Persona

角色设定

Voice & Style

语气与风格

Frontmatter Schema

前置元数据（Frontmatter）规范

Field Details

字段详情

Title Patterns by Post Type

按文章类型划分的标题格式

Author Byline

作者署名栏

Conventions

规范

Universal Post Structure

通用文章结构

Post Type Templates

按文章类型划分的模板

Major Release Announcement

重大版本发布公告

What's new in React X.Y {/whats-new/}

What's new in React X.Y {/whats-new/}

Feature Name {/feature-name/}

Feature Name {/feature-name/}

Improvements in React X.Y {/improvements/}

Improvements in React X.Y {/improvements/}

Improvement Name {/improvement-name/}

Improvement Name {/improvement-name/}

How to upgrade {/how-to-upgrade/}

How to upgrade {/how-to-upgrade/}

Changelog {/changelog/}

Changelog {/changelog/}

React {/react/}

React {/react/}

Upgrade Guide

升级指南

Stepping stone version {/stepping-stone/}

Stepping stone version {/stepping-stone/}

Installing {/installing/}

Installing {/installing/}

Codemods {/codemods/}

Codemods {/codemods/}

Run all React [VERSION] codemods {/run-all-codemods/}

Run all React [VERSION] codemods {/run-all-codemods/}

Breaking changes {/breaking-changes/}

Breaking changes {/breaking-changes/}

Removed: apiName {/removed-api-name/}

Removed: apiName {/removed-api-name/}

New deprecations {/new-deprecations/}

New deprecations {/new-deprecations/}

Deprecated: apiName {/deprecated-api-name/}

Deprecated: apiName {/deprecated-api-name/}

React Labs Research Update

React实验室研究更新

Feature Name {/feature-name/}

Feature Name {/feature-name/}

Subsection {/subsection/}

Subsection {/subsection/}

Research Area {/research-area/}

Research Area {/research-area/}

React Conf Recap

React大会回顾

Day 1 {/day-1/}

Day 1 {/day-1/}

Day 2 {/day-2/}

Day 2 {/day-2/}

Q&A {/q-and-a/}

Q&A {/q-and-a/}

And more... {/and-more/}

And more... {/and-more/}

Thank you {/thank-you/}

Thank you {/thank-you/}

Feature/Tool Announcement

功能/工具发布公告

tl;dr {/tldr/}

Removed:
`apiName`
{/removed-api-name/}

Removed:
`apiName`
{/removed-api-name/}

Deprecated:
`apiName`
{/deprecated-api-name/}

Deprecated:
`apiName`
{/deprecated-api-name/}

`<Intro>`
Pattern

`<Intro>`
组件格式

`<Note>`
Patterns

`<Note>`
组件格式

`<TerminalBlock>`
Pattern

`<TerminalBlock>`
组件格式

`<YouTubeIframe>`
Pattern

`<YouTubeIframe>`
组件格式