cline/docs/contributing/documentation-guide.mdx

---
title: "Documentation Guide"
sidebarTitle: "Documentation Guide"
description: "How to write and contribute to Cline documentation"
---

Cline's documentation lives in the `docs/` directory and uses [Mintlify](https://mintlify.com) for rendering. This guide covers how to write docs that match Cline's established style.

## Using the Documentation Workflow

The fastest way to create documentation is using the `/write-docs` workflow. Type `/write-docs` in Cline and describe what you want to document. Cline guides you through a 4-step process:

1. **Research**: Examine existing docs structure and patterns
2. **Scope**: Clarify audience, doc type, and key use cases
3. **Outline**: Select a template and create structure
4. **Write**: Generate documentation following style guidelines

The workflow file lives at `.clinerules/workflows/write-docs.md` and contains templates, style rules, and examples.

## Documentation Principles

### Write for Developers

Your audience is developers who value their time. Get to the point. Every sentence should either help them understand something or help them do something.

```markdown
# Good
Switch to bash in Cline Settings → Terminal → Default Terminal Profile.

# Bad
Users who are experiencing issues may find it helpful to navigate to the 
Cline settings menu where they can locate the terminal configuration 
options and subsequently modify the default terminal profile setting.
```

### Show Real Examples

Abstract descriptions don't help anyone. Show actual code, real file paths, and concrete implementations.

```markdown
# Good
I use `/deep-planning` whenever I'm building features that touch multiple 
parts of the codebase. For example, when adding authentication, Cline 
mapped every endpoint and created a migration plan that avoided breaking changes.

# Bad
The deep planning feature can be utilized for various complex tasks 
that may require careful consideration and planning.
```

### Use Active Voice

Cline does things. Files don't get created by Cline, Cline creates files.

```markdown
# Good
Cline reads your project files and builds context automatically.

# Bad
Project files are read and context is built automatically.
```

### Use Neutral Pronouns for Cline

Refer to Cline as "it" not "he". Cline is software, not a person.

```markdown
# Good
When Cline encounters an error, it suggests fixes.

# Bad
When Cline encounters an error, he suggests fixes.
```

## File Format

All documentation uses MDX format with YAML frontmatter:

```yaml
---
title: "Full Page Title"
sidebarTitle: "Shorter Nav Title"  # optional
description: "One sentence for SEO"  # optional but recommended
---
```

### Adding New Pages

After creating a new `.mdx` file, add it to `docs/docs.json` in the appropriate navigation group:

```json
{
  "group": "Features",
  "pages": [
    "features/existing-page",
    "features/your-new-page"
  ]
}
```

## Mintlify Components

Use these components appropriately throughout your docs.

### Frame

Wrap all images and videos:

```jsx
<Frame>
  <img 
    src="https://storage.googleapis.com/cline_public_images/docs/assets/filename.png" 
    alt="Descriptive alt text" 
  />
</Frame>
```

### Callouts

Use sparingly and purposefully:

```jsx
<Tip>Helpful suggestions that improve the experience.</Tip>
<Note>Important information the reader needs to know.</Note>
<Warning>Something that could cause problems if ignored.</Warning>
```

### Steps

For sequential procedures:

```jsx
<Steps>
  <Step title="Install the Extension">
    Search for "Cline" in the VS Code marketplace.
  </Step>
  <Step title="Configure Your Model">
    Open settings and add your API key.
  </Step>
</Steps>
```

### Cards

For navigation and feature overviews:

```jsx
<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/getting-started/installing-cline">
    Install Cline and set up your first project.
  </Card>
  <Card title="Features" icon="wand-magic-sparkles" href="/core-workflows/plan-and-act">
    Explore what Cline can do.
  </Card>
</CardGroup>
```

## Style Rules

Quick reference for consistent documentation:

| Do | Don't |
|---|---|
| Use "use" | Use "utilize" |
| Keep sentences under 25 words | Write run-on sentences |
| Use bullet points for lists | Write walls of text |
| Show where things are in the UI | Assume users can find features |
| Cross-link related docs | Leave readers stranded |
| Use code blocks with language tags | Use inline code for long snippets |

### Avoid These Patterns

- Em dashes and emojis
- Starting with "This document explains..."
- The **Bold Text**: description pattern
- Explaining obvious things
- Passive voice

## Previewing Changes

Run the docs locally to preview your changes:

```bash
cd docs
npm install  # first time only
npm run dev
```

Open `http://localhost:3000` to see your changes in real time.

## Related Resources

<CardGroup cols={2}>
  <Card title="Documentation Templates" icon="file-lines" href="/contributing/doc-templates">
    Templates for different documentation types.
  </Card>
  <Card title="Workflows" icon="diagram-project" href="/customization/workflows">
    Learn about Cline's workflow system.
  </Card>
</CardGroup>