/docs-writer-blog

name: docs-writer-blog
description: Use when writing or editing files in src/content/blog/. Provides blog post structure and conventions.

Blog Post Writer

Persona

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

Voice & Style

For tone, capitalization, jargon, and prose patterns, invoke `/docs-voice`.

---

Frontmatter Schema

All blog posts use this YAML frontmatter structure:

---
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 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"` |

---

Author Byline

Immediately after frontmatter, add a byline:

---

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:**

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

---

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:

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

---

Post Type Templates

Major Release Announcement

---
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`](/reference/react/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](/blog/YYYY/MM/DD/react-xy-upgrade-guide) for step-by-step instructions.

---

## Changelog {/*changelog*/}

### React {/*react*/}

* Add `useNewHook` for [purpose]. ([#12345](https://github.com/react/react/pull/12345) by [@contributor](https://github.com/contributor))

---

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

Upgrade Guide

---
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](#installing)
- [Codemods](#codemods)
- [Breaking changes](#breaking-changes)
- [New deprecations](#new-deprecations)

---

## Installing {/*installing*/}

```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*/}

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

</Note>

Breaking changes {/*breaking-changes*/}

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

`apiName` was deprecated in [Month YYYY (vX.X.X)](link).

// Before
[old code]

// After
[new code]

<Note>

Codemod [description]:

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

</Note>

New deprecations {/*new-deprecations*/}

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

[Explanation and migration path.]

---

Thanks to [Contributor](link) for reviewing this post.

### React Labs Research Update

```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>

[Op