Documentation Writer for Nuxt Ecosystem

Writing guidance for blog posts and documentation following patterns from official Nuxt websites.

When to Use

• Writing blog posts for Nuxt ecosystem projects
• Creating or editing documentation pages
• Ensuring consistent writing style across content

Writing Standard

Override: When writing documentation, maintain proper grammar and complete sentences. The "sacrifice grammar for brevity" rule does NOT apply here.

Documentation must be:

• Grammatically correct
• Clear and unambiguous
• Properly punctuated
• Complete sentences (not fragments)

Brevity is still valued, but never at the cost of clarity or correctness.

Related Skills

For component and syntax details, use these skills:

Skill	Use For
nuxt-content	MDC syntax, prose components, code highlighting
nuxt-ui	Component props, theming, UI patterns

Available References

Reference	Purpose
references/writing-style.md	Voice, tone, sentence structure
references/content-patterns.md	Blog frontmatter, structure, component patterns

Loading Files

Consider loading these reference files based on your task:

• references/writing-style.md - if writing prose, improving voice/tone, or structuring sentences
• references/content-patterns.md - if creating blog posts, setting up frontmatter, or using MDC components

DO NOT load all files at once. Load only what's relevant to your current task.

Quick Reference

Writing Patterns

Pattern	Example
Subject-first	"The useFetch composable handles data fetching."
Imperative	"Add the following to nuxt.config.ts."
Contextual	"When using authentication, configure..."

Modal Verbs

Verb	Meaning
can	Optional
should	Recommended
must	Required

Component Patterns (WHEN to use)

Need	Component
Info aside	::note
Suggestion	::tip
Caution	::warning
Required	::important
CTA	:u-button{to="..." label="..."}
Multi-source code	::code-group

For component props: see nuxt-ui skill

Headings

• H1 (#): No backticks — they don't render properly
• H2-H4: Backticks work fine

Checklist

• Active voice (85%+)
• Present tense
• 2-4 sentences per paragraph
• Explanation before code
• File path labels on code blocks
• Appropriate callout types
• No backticks in H1 headings

---

Referenced Files

The following files are referenced in this skill and included for context.

references/writing-style.md

# Writing Style

Sentence structure, voice, tone, and paragraph patterns for Nuxt documentation.

## Sentence Patterns

### Subject-First Declarative (60%)

Place subject first, verb follows. Clear and direct.

The useFetch composable handles data fetching automatically. Nuxt provides a powerful auto-import system. This option controls module behavior during development.

### Imperative Instructions (25%)

Direct commands for actions. Implied "you" subject.

Add the following to nuxt.config.ts. Create a new file in server/api. Run the development server to see changes.

### Contextual Openers (15%)

Context before main clause. For conditionals and prerequisites.

When using authentication, configure the session handler. During SSR, the composable fetches data before hydration. After installing the module, restart the server.

## Voice

### Active Voice (85%)

Subject performs action. Prefer this.

| Active (use)                    | Passive (avoid)                       |
| ------------------------------- | ------------------------------------- |
| The module creates a connection | A connection is created by the module |
| You can override defaults       | Defaults can be overridden            |
| Nuxt handles routing            | Routing is handled by Nuxt            |

### When Passive is OK (15%)

- Actor unknown: "The file is loaded during startup."
- Object more important: "Data is cached for 5 minutes."
- System behavior: "Routes are generated from pages directory."

## Tense

**Present (90%)**: Instructions and behavior
**Future (5%)**: Consequences ("This will create an endpoint")
**Past (5%)**: Changelogs only

## Modal Verbs

| Verb     | Meaning           | Example                          |
| -------- | ----------------- | -------------------------------- |
| `can`    | Optional (40%)    | "You can customize colors."      |
| `should` | Recommended (30%) | "You should validate input."     |
| `may`    | Possibility (20%) | "This may cause issues."         |
| `must`   | Required (10%)    | "You must install dependencies." |

Avoid weak modals: `might`, `could`, `would`

## Direct Address

**Guides/tutorials**: Use "you" (70% of content)
**API references**: Neutral voice, no "you"

Stay consistent within sections.

## Paragraphs

**Length**: 2-4 sentences max
**Structure**: Topic sentence first, then supporting details

Route middleware runs before navigation. Use it to check authentication or redirect users. Define middleware in the middleware directory.

## Opening Sentences

### Page Openings

Define what it is, its purpose, key benefits:

Server routes create API endpoints in your Nuxt app. They run on the server with access to databases and external services.

Avoid: "This page describes...", "In this guide...", "Let's explore..."

### Section Openings

Introduce topic and why it matters:

Configuration

The module accepts several options that control its behavior.

## Tone by Content Type

| Type            | Tone                         |
| --------------- | ---------------------------- |
| Getting Started | Welcoming, encouraging       |
| Guides          | Instructional, supportive    |
| API Reference   | Precise, neutral             |
| Troubleshooting | Empathetic, solution-focused |

## Word Choice

| Avoid           | Use         |
| --------------- | ----------- |
| utilize         | use         |
| implement       | add, create |
| leverage        | use         |
| in order to     | to          |
| due to the fact | because     |

## Common Mistakes

- Starting with "It" or "This" (unclear antecedent)
- Stacking prepositions ("the value of the property of the config")
- Overusing "Note that" (just state the fact)
- Burying important info at end of long sentences

references/content-patterns.md

# Content Patterns

Blog post structure, frontmatter, and component patterns for Nuxt ecosystem documentation.

## Blog Post Frontmatter

```yaml
---
title: Post Title
description: Brief description for SEO and previews (under 160 chars)
navigation: false
image: /assets/blog/slug.png
authors:
  - name: Author Name
    avatar:
      src: https://github.com/username.png
    to: https://x.com/username
date: 2025-11-05T10:00:00.000Z
category: Release
---

Categories: Release (version announcements), Article (tutorials, guides)

Author links: GitHub, X/Twitter, Bluesky (https://bsky.app/profile/...)

Blog Post Structure

1. Opening (1-2 paragraphs) - Announce what's new, why it matters
2. Key callout - ::note or ::callout with requirements/prerequisites
3. Feature sections - ## Emoji Feature Name headers
4. Code examples - With file path labels
5. Breaking changes - If release post
6. Thank you - Credit contributors
7. Resources - Links to docs, repo
8. Release link - ::read-more to full changelog

Recommended Modules

For enhanced documentation features:

Module	Purpose
nuxt-content-twoslash	TwoSlash for Nuxt Content - inline TypeScript type hints in code blocks

Installation

pnpm add -D nuxt-content-twoslash

export default defineNuxtConfig({
  modules: ['nuxt-content-twoslash', '@nuxt/content'] // twoslash before content
})

Component Patterns

Use the right component for the right purpose:

Need	Component	When
Background info	::note	Supplementary context
Best practice	::tip	Recommendations
Potential issue	::warning	Things that could go wrong
Must-know	::important	Required actions
Danger	::caution	Destructive operations
CTA button	:u-button{to="..." label="..."}	Downloads, external links
Package managers	::code-group{sync="pm"}	pnpm/npm/yarn variants
Expandable	::collapsible{title="..."}	Advanced details
Images	::carousel{items: [...]}	Multiple screenshots
Sequential steps	::steps	Multi-step instructions

For component props/details: see nuxt-ui skill

Steps Component

The ::steps component auto-renders step numbers. Do NOT include numbers in step titles — they'll be duplicated.

<!-- ✅ Correct -->
::steps
### Install the module
### Configure nuxt.config.ts
### Restart dev server
::

<!-- ❌ Wrong (numbers will duplicate) -->
::steps
### 1. Install the module
### 2) Configure nuxt.config.ts
### Step 3: Restart dev server
::

Code Block Labels

Always include file path:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/content']
})
```

```vue [app/pages/index.vue]
<template>
  <div>Hello</div>
</template>
```

```bash
pnpm add @nuxt/content
```

YAML Props Format

For components with multiple props, use YAML frontmatter:

::read-more
---
icon: i-simple-icons-github
target: _blank
to: https://github.com/nuxt/nuxt/releases/tag/v4.0.0
---
Read the full release notes.
::

::carousel
---
items:
  - /assets/blog/image-1.png
  - /assets/blog/image-2.png
---
::

Cross-References

Link to related content:

<!-- Inline link -->
See the [configuration guide](/docs/getting-started/configuration).

<!-- Read-more block -->
::read-more{to="/docs/api/composables/use-fetch"}
::

<!-- With custom text and icon -->
::read-more
---
icon: i-simple-icons-github
to: https://github.com/nuxt/nuxt
target: _blank
---
View the source code.
::

For MDC syntax details: see nuxt-content skill (rendering.md)