Blog Post Writer

docs-writer-blog

If you're working on the React docs blog, this skill knows the house style.

reactjs/react.dev·0installs11.8KstarsDocumentation

SKILL.md

Full skill instructions

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:

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.)

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).

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

[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.]

### 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](url) for reviewing this post._

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

React Conf Recap

---
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.](youtube-url)_

[Description of day 1 opening and keynote highlights.]

Watch the full day 1 keynote here:

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

## Day 2 {/*day-2*/}

_[Watch the full day 2 stream here.](youtube-url)_

[Day 2 summary.]

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

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

* [Q&A Title](youtube-url) hosted by [Host](url)

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

We also heard talks including:
* [Talk Title](youtube-url) by [Speaker](url)

## Thank you {/*thank-you*/}

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

See you next time!

Feature/Tool Announcement

---
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](/path).
* 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.](/path/to/docs)

## What's next {/*whats-next*/}

[Future plans and next steps.]

## Thank you {/*thank-you*/}

[Acknowledgments to contributors.]

---

Thanks to [Reviewer](url) for reviewing this post.

Security Announcement

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

Timeline {/timeline/}

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.


---

## Heading Conventions

### ID Syntax

All headings require IDs using CSS comment syntax:

```markdown
## Heading Text {/*heading-id*/}

ID Rules

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

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

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

Always wrap opening paragraph:

<Intro>

React 19 is now available on npm!

</Intro>

`<Note>` Patterns

Simple note:

<Note>

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

</Note>

Titled note (H4 inside):

<Note>

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

To help with the upgrade, we've published `[email protected]`...

</Note>

`<TerminalBlock>` Pattern

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

`<YouTubeIframe>` Pattern

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

External Links

Type	Pattern
GitHub PR	`[#12345](https://github.com/react/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)`

"See docs" Pattern

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

Changelog Format

Bullet Pattern

* Add `useTransition` for concurrent rendering. ([#10426](https://github.com/react/react/pull/10426) by [@acdlite](https://github.com/acdlite))
* Fix `useReducer` observing incorrect props. ([#22445](https://github.com/react/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

Section Organization

## Changelog {/*changelog*/}

### React {/*react*/}

* [changes]

### React DOM {/*react-dom*/}

* [changes]

Acknowledgments Format

Post-closing Thanks

---

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

Or italicized:

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

Update Notes

For post-publication updates:

<Note>

[Updated content]

-----

_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

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

Updating Old Posts

Never break existing URLs; add redirects when URLs change

Don't rewrite history; add update notes instead:

<Note>

[Updated information]

-----

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

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.

Install skill

Copy and run in your terminal

npx -y skills add reactjs/react.dev --skill docs-writer-blog

View on GitHub

.claude/skills/docs-writer-blog

Blog Post Writer

SKILL.md

Blog Post Writer

Persona

Voice & Style

Frontmatter Schema

Field Details

Title Patterns by Post Type

Author Byline

Conventions

Universal Post Structure

Post Type Templates

Major Release Announcement

Upgrade Guide

Codemods {/​codemods/​}

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

Breaking changes {/​breaking-changes/​}

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

New deprecations {/​new-deprecations/​}

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

React Conf Recap

Feature/​Tool Announcement

Security Announcement

Timeline {/​timeline/​}

Attribution {/​attribution/​}

ID Rules

Heading Patterns

Component Usage Guide

Blog-Appropriate Components

<Intro> Pattern

<Note> Patterns

<TerminalBlock> Pattern

<YouTubeIframe> Pattern

Link Patterns

Internal Links

External Links

"See docs" Pattern

Changelog Format

Bullet Pattern

Section Organization

Acknowledgments Format

Post-closing Thanks

Update Notes

Tone & Length by Post Type

Do's and Don'ts

Updating Old Posts

Critical Rules

Components Reference

Codemods {/codemods/}

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

Breaking changes {/breaking-changes/}

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

New deprecations {/new-deprecations/}

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

Feature/Tool Announcement

Timeline {/timeline/}

Attribution {/attribution/}

`<Intro>` Pattern

`<Note>` Patterns

`<TerminalBlock>` Pattern

`<YouTubeIframe>` Pattern