Coolify Documentation Assistant

Expert assistant for working with the Coolify documentation repository. Coolify is an open-source self-hosting platform, and this skill helps you navigate, maintain, and contribute to its VitePress-based documentation site.

What This Skill Does

This skill provides comprehensive guidance for working with the Coolify documentation repository, including:

Instructions

1. Understand the Branch Strategy

**CRITICAL**: All pull requests MUST target the `next` branch, NEVER `main`.

When creating pull requests, always verify the base branch is set to `next`.

2. Technology Stack and Setup

The documentation uses:

**Setup commands:**

```bash

Install dependencies

bun install

Run development server (http://localhost:5173/docs/)

bun run dev

Build for production

bun run build

Preview production build

bun run preview

Convert OpenAPI YAML to JSON (after updating API spec)

bun run transform-openapi

```

3. Directory Structure

Key directories:

4. Image Handling

**ALWAYS** follow these image conventions:

1. **Format**: All images MUST be `.webp` format

2. **Location**: Store in `docs/public/images/[section]/`

3. **Paths**: Use absolute paths: `/docs/images/...`

4. **Component**: Always use the `ZoomableImage` component:

```vue

<ZoomableImage src="/docs/images/section/image.webp" alt="Descriptive text" />

```

Never use standard markdown image syntax for documentation images.

5. Service Documentation Management

**File Naming Rules** for `docs/services/`:

1. Use **kebab-case lowercase** for all filenames

2. Match the base service name from `service-templates-latest.json`

3. Do NOT use camelCase (e.g., `denoKV` → `denokv.md`)

4. Include version numbers when specified (e.g., `mautic5.md`)

5. Use compound names when specified (e.g., `ente-photos.md`)

**Source of truth** for service names:

```

https://raw.githubusercontent.com/coollabsio/coolify/refs/heads/v4.x/templates/service-templates-latest.json

```

**When adding/modifying services, update these 3 locations:**

1. `docs/services/{name}.md` - The documentation file

2. `docs/.vitepress/theme/components/Services/List.vue` - Service listing (slug MUST match filename)

3. `nginx/redirects.conf` - URL redirects (when renaming/removing)

4. `docs/public/images/services/` - Service logo

**Disabling services:**

6. Content Guidelines

**Writing style:**

**Required frontmatter:**

```yaml

---

title: Page Title

description: Brief description for SEO

---

```

**Custom containers:**

```markdown

::: success

Success message

:::

::: warning

Warning message

:::

::: danger

Danger message

:::

::: info

Info message

:::

::: tip

Tip message

:::

```

**Links:**

7. Custom Vue Components

Located in `docs/.vitepress/theme/components/`:

8. Build and Deployment

**Docker build:**

Multi-stage build using `oven/bun` (builder) and `nginx-unprivileged` (runtime).

**CI/CD Workflows:**

9. Custom VitePress Plugins

1. **vitepress-openapi**: Auto-generates API docs from OpenAPI spec (fetched from GitHub v4.x branch)

2. **vitepress-plugin-coolbot**: Converts markdown to plain text for AI/RAG systems (generates `llms-text.json`)

3. **vitepress-plugin-llms**: Generates llms.txt for LLM consumption

4. **vitepress-plugin-tabs**: Enables tabbed content blocks

5. **vitepress-plugin-group-icons**: Adds icons to code group labels

10. Troubleshooting

| Issue | Solution |

|-------|----------|

| Images not displaying | Check path is absolute (`/docs/images/...`) |

| Links broken after rename | Update all 3 locations (file, List.vue, redirects.conf) |

| Build fails | Check frontmatter YAML syntax |

| Service not showing | Verify slug in List.vue matches filename |

Important Notes

Reference Links