create-documentation

You are creating proper markdown documentation for a feature or guide in the Documenso documentation site.

Read WRITING_STYLE.md first for tone, formatting conventions, and anti-patterns to avoid.

Your Task

1. Identify the scope - Based on the conversation context, determine what feature or topic needs documentation. Ask the user if unclear.
2. Identify the audience - Is this for Users, Developers, or Self-Hosters?
3. Read the source code - Understand the feature, API, or configuration being documented.
4. Read existing docs - Check apps/docs/content/docs/ for documentation to update.
5. Write comprehensive documentation - Create or update MDX docs following the patterns below.
6. Update navigation - Add to the relevant meta.json if creating a new page.

Documentation Framework

This project uses Fumadocs. All documentation lives in apps/docs/content/docs/ as MDX files. The docs app is a Next.js app at apps/docs/.

Documentation Structure

apps/docs/content/docs/
├── index.mdx              # Landing page with audience navigation
├── meta.json              # Root navigation: guides + resources
├── users/                 # Application usage guides
│   ├── meta.json          # { "root": true, "pages": [...] }
│   ├── getting-started/   # Account creation, first document
│   ├── documents/         # Upload, recipients, fields, send
│   │   └── advanced/      # AI detection, visibility, placeholders
│   ├── templates/         # Create and use templates
│   ├── organisations/     # Overview, members, groups, SSO, billing
│   │   ├── single-sign-on/
│   │   └── preferences/
│   └── settings/          # Profile, security, API tokens
├── developers/            # API and integration docs
│   ├── meta.json          # { "root": true, "pages": [...] }
│   ├── getting-started/   # Authentication, first API call
│   ├── api/               # Documents, recipients, fields, templates, teams
│   ├── webhooks/          # Setup, events, verification
│   ├── embedding/         # Authoring, direct links, CSS vars, SDKs
│   │   └── sdks/          # React, Vue, Svelte, Solid, Preact, Angular
│   ├── examples/          # Common workflows
│   ├── local-development/ # Quickstart, manual, translations
│   └── contributing/      # Contributing translations
├── self-hosting/          # Self-hosting documentation
│   ├── meta.json          # { "root": true, "pages": [...] }
│   ├── getting-started/   # Quick start, requirements, tips
│   ├── deployment/        # Docker, docker-compose, Kubernetes, Railway
│   ├── configuration/     # Environment, database, email, storage
│   │   ├── signing-certificate/  # Local, Google Cloud HSM, timestamp
│   │   └── advanced/      # OAuth providers, AI features
│   └── maintenance/       # Upgrades, backups, troubleshooting
├── concepts/              # Shared across audiences
│   └── ...                # Document lifecycle, field types, signing
├── compliance/            # eSign, GDPR, standards, certifications
└── policies/              # Terms, privacy, security, licenses

Where to Put Documentation

Type	Location	When to use
User Guide	apps/docs/content/docs/users/<section>/	UI workflows for using the Documenso web app
Developer Guide	apps/docs/content/docs/developers/<section>/	API reference, SDK guides, webhooks, embedding
Self-Hosting	apps/docs/content/docs/self-hosting/<section>/	Deployment, configuration, environment variables
Concept	apps/docs/content/docs/concepts/	Cross-audience concepts (document lifecycle, etc.)
Compliance	apps/docs/content/docs/compliance/	Legal and regulatory documentation

Navigation (meta.json)

Each directory has a meta.json controlling navigation order:

{
  "title": "Section Title",
  "pages": ["getting-started", "documents", "templates"]
}

Top-level audience sections use "root": true:

{
  "title": "Users",
  "description": "Send and sign documents",
  "root": true,
  "pages": ["getting-started", "documents", "templates", "organisations", "settings"]
}

Root meta.json uses ---Label--- for section dividers:

{
  "title": "Documentation",
  "pages": [
    "---Guides---",
    "users",
    "developers",
    "self-hosting",
    "---Resources---",
    "concepts",
    "compliance",
    "policies"
  ]
}

MDX File Format

Frontmatter

Every page needs frontmatter:

---
title: Upload Documents
description: Upload documents to Documenso to prepare them for signing. Covers supported formats, file size limits, and upload methods.
---

Fumadocs Components

Import components at the top of the file (after frontmatter):

import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

;

Callouts (use sparingly for warnings, beta features, security):

<Callout type="info">Informational note about behavior.</Callout>

<Callout type="warn">Warning about potential issues or breaking changes.</Callout>

<Callout type="error">Critical warning about data loss or security.</Callout>

Steps (for sequential UI instructions):

{/* prettier-ignore */}
<Steps>
  <Step>
    ### Step title

    Step description.

  </Step>
  <Step>
    ### Next step

    Next description.

  </Step>
</Steps>

Tabs (for multiple approaches or platforms):

<Tabs items={['cURL', 'JavaScript', 'Python']}>
  <Tab value="cURL">```bash curl -X POST ... ```</Tab>
  <Tab value="JavaScript">```typescript const response = await fetch(...) ```</Tab>
</Tabs>

Page Structure by Audience

User Documentation

---
title: Feature Name
description: Brief description for SEO and previews.
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Limitations

| Limitation        | Value    |
| ----------------- | -------- |
| Supported format  | PDF only |
| Maximum file size | 50MB     |

## How to Do the Thing

{/* prettier-ignore */}
<Steps>
  <Step>
    ### Navigate to the page

    Open **Settings > Feature**.

  </Step>
  <Step>
    ### Configure the setting

    Fill in the required fields and click **Save**.

  </Step>
</Steps>

---

## See Also

- [Related Guide](/docs/users/related)

Developer Documentation

---
title: Documents API
description: Create, manage, and send documents for signing via the API.
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Callout type="warn">
  This guide may not reflect the latest endpoints. For an always up-to-date reference, see the
  [OpenAPI Reference](https://openapi.documenso.com).
</Callout>

## Overview

Brief description of the resource and what you can do with it.

## Resource Object

| Property | Type   | Description       |
| -------- | ------ | ----------------- |
| `id`     | string | Unique identifier |
| `status` | string | Current status    |

## Create a Resource

```typescript
const response = await fetch('https://app.documenso.com/api/v2/document', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Service Agreement',
  }),
});
```

---

See Also

• Related Guide

### Self-Hosting Documentation

```mdx
---
title: Environment Variables
description: Complete reference for all environment variables used to configure Documenso.
---

## Required Variables

| Variable           | Description                                      |
| ------------------ | ------------------------------------------------ |
| `NEXTAUTH_SECRET`  | Secret key for session encryption (min 32 chars)  |
| `DATABASE_URL`     | PostgreSQL connection URL                        |

---

## Optional Variables

| Variable       | Default | Description            |
| -------------- | ------- | ---------------------- |
| `PORT`         | `3000`  | Port the server runs on |

---

## See Also

- [Database Configuration](/docs/self-hosting/configuration/database)

Documentation Audiences

Tailor content to the audience:

• User docs: Focus on UI workflows, bold UI elements (Settings, Save), use > for navigation paths (Settings > Team > Members), number sequential steps, no code required
• Developer docs: API/SDK examples, authentication, webhooks, code samples in TypeScript, link to OpenAPI reference
• Self-hosting docs: Deployment guides, environment variables, Docker/non-Docker approaches, system requirements, troubleshooting

Guidelines

See WRITING_STYLE.md for complete guidelines. Key points:

• Tone: Direct, second-person, no emojis, no excessive personality
• Examples: Progressive complexity, all must be valid TypeScript
• Tables: Use Sharp-style nested parameter tables for API docs
• Callouts: Use sparingly for warnings, beta features, security
• Cross-references: Link related docs, add "See Also" sections
• Navigation: Update meta.json when adding new pages
• Limitations: Explicitly list what is NOT supported
• Images: Use .webp format, store in apps/docs/public/

Process

1. Identify the audience - Users, Developers, or Self-Hosters?
2. Explore the code - Read source files to understand the feature
3. Check existing docs - Look in apps/docs/content/docs/ for related pages
4. Draft the structure - Outline sections before writing
5. Write content - Fill in each section following audience-specific patterns
6. Update navigation - Add to relevant meta.json if creating a new page
7. Add cross-references - Link from related docs, add "See Also" section

Begin

Analyze the conversation context to determine the documentation scope, read the relevant source code, and create comprehensive MDX documentation in apps/docs/content/docs/.