Document Writer

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:

Available References

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

Modal Verbs

Component Patterns (WHEN to use)

For component props: see nuxt-ui skill

Headings

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

Workflow

1. Load relevant reference file (writing-style.md for prose, content-patterns.md for structure) 2. Draft content using active voice and present tense 3. Apply the checklist below to verify quality — if any item fails, revise and re-check 4. Verify callout types match intent (note/tip/warning/important)

Example

# Getting Started with Authentication

Nuxt Better Auth provides a simple way to add authentication to your application.
Configure the module in your `nuxt.config.ts` to get started.

::note
Authentication requires a database connection. See the [database setup](/docs/database) guide for details.
::

## Installation

Add the module to your project:

~~~bash [Terminal]
pnpm add @onmax/nuxt-better-auth
~~~

The module auto-imports the `useUserSession` composable. Access the current user session from any component.

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

Content Patterns

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

Blog Post Frontmatter

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

Installation

pnpm add -D nuxt-content-twoslash

```ts [nuxt.config.ts] 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'] })

<template> <div>Hello</div> </template>

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)

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.

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

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

Word Choice

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