Documentation Editing

This skill covers creating and modifying documentation for Case.dev services using Mintlify.

Key Files

File	Purpose
apps/docs-mintlify/docs.json	Navigation menu structure
apps/docs-mintlify/services.mdx	All Services page
apps/docs-mintlify/openapi.json	API Reference endpoints (generated from router metadata)
apps/docs-mintlify/<service>/	Service documentation pages
apps/router/server/routes/	Source of truth for public endpoint OpenAPI metadata

Before Making Changes

Study existing documentation to match style and conventions:

1. Read 2-3 existing service docs (e.g., llms/, vault/, voice/)
2. Note the frontmatter format, heading structure, component usage
3. Match the tone: concise, action-oriented, developer-focused
4. For multi-language examples, use apps/docs-mintlify/llms/index.mdx as the formatting guide

Adding a New Service

1. Create Documentation Pages

Create a folder under apps/docs-mintlify/<service-name>/ with:

<service-name>/
├── index.mdx      # Overview (title: "<Service> Overview")
├── <feature>.mdx  # Feature pages (no icons in frontmatter)
└── ...

Use kebab-case for folder names (e.g., web-search/, ai-governance/).

2. Add to Navigation Menu

Edit docs.json → find the appropriate tab → add group:

{
  "group": "Service Name",
  "icon": "icon-name",
  "pages": ["service-name/index", "service-name/feature-one", "service-name/feature-two"]
}

• Add icon to the group only, not individual pages
• Overview page title should be <Service> Overview to distinguish from group name
• Place under "Platform" for services, or appropriate section

3. Add to All Services Page

Edit services.mdx:

1. Add a Card in the CardGroup:

<Card title="Service Name" icon="icon-name" href="/service-name/index">
  One-sentence description of what this service does.
</Card>

2. Add a row to the decision table:

| Use case description | [Service Name](/service-name/index) |

4. Add to API Reference (if endpoints exist)

Do not edit apps/docs-mintlify/openapi.json by hand.

To expose endpoints in the API Reference:

1. Add or update export const openapi = { ... } in the route file under apps/router/server/routes/
2. Run cd apps/router && bun run openapi:compile
3. Verify the generated spec in apps/docs-mintlify/openapi.json

bun run openapi:compile also refreshes apps/router/openapi.json, apps/router/generated/services.json, and apps/router/generated/services-catalog.json.

If you change apps/docs-mintlify/services.mdx, rerun cd apps/router && bun run openapi:compile so the services catalog stays in sync.

Mintlify Components

Common components for documentation:

<Card title="Title" icon="icon" href="/path">Description</Card>
<CardGroup cols={2}>...</CardGroup>
<CodeGroup>...</CodeGroup>
<Info>Informational note</Info>
<Warning>Warning message</Warning>
<Tip>Helpful tip</Tip>

Codeblock Conventions

Use apps/docs-mintlify/llms/models.mdx as the canonical reference for SDK code examples.

Rules

1. Every code block needs an explicit title="..." — Mintlify will not render tabs for blocks that omit the title attribute. This applies to all languages, including typescript, python, and go.
2. Wrap multi-language examples in <CodeGroup>
3. Use this exact tab order (matching the rest of the docs): TypeScript → Python → C# → Java → PHP → cURL → Go → CLI
4. Include all SDK languages when providing code examples. Omit CLI only if there is no CLI equivalent.
5. Prefer the existing SDK method names and import style from current docs over inventing new examples

Example skeleton

<CodeGroup>

```typescript title="TypeScript"
import Casedev from 'casedev'
const client = new Casedev({ apiKey: process.env.CASEDEV_API_KEY })
// ...
```

```python title="Python"
import casedev
client = casedev.Casedev(api_key=os.environ['CASEDEV_API_KEY'])
# ...
```

```csharp title="C#"
using Casedev;
CasedevClient client = new() { ApiKey = Environment.GetEnvironmentVariable("CASEDEV_API_KEY") };
// ...
```

```java title="Java"
import dev.case.api.client.CasedevClient;
import dev.case.api.client.okhttp.CasedevOkHttpClient;
CasedevClient client = CasedevOkHttpClient.fromEnv();
// ...
```

```php title="PHP"
<?php
require 'vendor/autoload.php';
$client = new \CaseDev\Client(apiKey: getenv('CASEDEV_API_KEY') ?: 'sk_case_YOUR_API_KEY');
// ...
```

```bash title="cURL"
curl https://api.case.dev/... \
  -H "Authorization: Bearer $CASE_API_KEY"
```

```go title="Go"
import "github.com/casemark/casedev-go"
client := casedev.NewClient()
// ...
```

```bash title="CLI"
casedev ...
```

</CodeGroup>

Verification

After making changes:

cd apps/router && bun run openapi:compile
cd apps/docs-mintlify && mintlify dev

Check for:

• Broken links (Mintlify reports these)
• Navigation renders correctly
• New pages are accessible
• API Reference reflects the generated spec
• Service catalog changes derived from services.mdx look correct

Stop and Ask

Stop and ask if:

• Adding a service that doesn't have implemented endpoints yet
• Changing navigation structure significantly
• Removing or renaming existing pages (could break external links)

Just proceed if:

• Adding new documentation for an existing service
• Fixing typos or improving descriptions
• Adding implemented endpoints through router openapi exports

Common Mistakes

1. Adding icons to subpages - Icons go on the group, not individual pages
2. Forgetting services.mdx - New services should appear on All Services
3. Editing generated OpenAPI files by hand - Update router metadata and recompile instead
4. Skipping bun run openapi:compile after services.mdx changes - This leaves generated/services-catalog.json stale
5. Dropping SDK languages inconsistently - Match the existing CodeGroup pattern when a page needs multi-language examples
6. Mismatched titles - Overview page should say "Overview" to avoid confusion with nav group
7. Missing title="..." on code blocks - Mintlify silently drops tabs that lack an explicit title. Always add title="TypeScript", title="Python", title="Go", etc. — even when the title matches the language tag
8. Wrong tab order - Tabs must follow: TypeScript → Python → C# → Java → PHP → cURL → Go → CLI. Deviating from this order creates an inconsistent experience across docs pages