adding-documentation-pages

Original source / Raw SKILL.md

---
name: adding-documentation-pages
description: Creates documentation pages for guides, tutorials, knowledge base articles, and troubleshooting content in docs/. Use when adding how-to guides, writing KB articles, creating troubleshooting docs, adding pages to get-started/, applications/, databases/, knowledge-base/, or integrations/. NOT for service pages - use adding-service-documentation for docs/services/.
allowed-tools: Read, Grep, Glob, Write, Edit
---

# Add Documentation Page

Create new documentation pages for the Coolify docs (guides, tutorials, KB articles, troubleshooting).

## When NOT to Use This Skill

**Use `adding-service-documentation` instead for:**
- Service pages in `docs/services/`
- One-click services from Coolify's catalog

Services require List.vue registration and logo handling covered by that skill.

## Quick Start

1. **Create file** in the appropriate section directory
2. **Add frontmatter** with `title` and `description`
3. **Write content** with clear headings
4. **Update sidebar** in `docs/.vitepress/config.mts` (if needed)
5. **Add images** using `<ZoomableImage>` component

## Documentation Sections

| Section | Path | Content Type |
|---------|------|--------------|
| Get Started | `docs/get-started/` | Introduction, installation, basics |
| Applications | `docs/applications/` | Framework deployment guides |
| Databases | `docs/databases/` | Database deployment docs |
| Knowledge Base | `docs/knowledge-base/` | How-tos, concepts, guides |
| Troubleshoot | `docs/troubleshoot/` | Problem-solution articles |
| Integrations | `docs/integrations/` | Third-party integration guides |

## Required Frontmatter

```yaml
---
title: "Page Title"
description: "SEO-friendly description (used in meta tags)."
---
```

## File Naming

- Use lowercase kebab-case: `my-guide.md`
- Be descriptive but concise

## Detailed References

**Page-specific:**
- [TEMPLATES.md](./TEMPLATES.md) - Ready-to-use page templates
- [SIDEBAR.md](./SIDEBAR.md) - How to update sidebar configuration

**Shared guidelines:**
- [FRONTMATTER.md](../_shared/FRONTMATTER.md) - Title, description, Open Graph
- [IMAGES.md](../_shared/IMAGES.md) - Image syntax and optimization
- [LINKS.md](../_shared/LINKS.md) - Internal and external link formatting
- [CONTAINERS.md](../_shared/CONTAINERS.md) - VitePress callout containers

## Key Rules

1. **Images**:
   - Small images/icons: use standard markdown `![alt](path)`
   - Screenshots/large images: use `<ZoomableImage>` component
   - Format: `.webp` preferred, absolute paths (`/docs/images/...`)
2. **Links**: Internal use absolute paths; external add `?utm_source=coolify.io`
3. **Sidebar**: Update `docs/.vitepress/config.mts` (starts ~line 130)

## Verification

- [ ] Frontmatter has `title` and `description`
- [ ] Screenshots use `<ZoomableImage>`
- [ ] External links have UTM parameters
- [ ] Page added to sidebar (if applicable)
- [ ] Renders at http://localhost:5173/docs/[path]

## Related Skills

- `adding-service-documentation` - For `docs/services/` pages
- `renaming-services` - Renaming service docs
- `disabling-services` - Deprecating services


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### TEMPLATES.md

```markdown
# Documentation Page Templates

Ready-to-use templates for different documentation types.

## Step-by-Step Guide

For how-to guides and tutorials:

```markdown
---
title: "How to Configure X"
description: "Learn how to configure X in Coolify for [benefit]."
---

# How to Configure X

Brief overview of what this guide covers.

## Prerequisites

- Prerequisite 1
- Prerequisite 2

## 1. First Step

Description of the first step.

<ZoomableImage src="/docs/images/section/guide/step-1.webp" alt="Step 1" />

## 2. Second Step

Description of the second step.

::: tip
Helpful tip for this step.
:::

## 3. Third Step

Description of the third step.

## Troubleshooting

### Common Issue 1

Solution to common issue.

## Related Resources

- [Related Guide](/path/to/guide)
- [External Documentation](https://example.com?utm_source=coolify.io)
```

## Troubleshooting Article

For problem-solution documentation:

```markdown
---
title: "Fix: Problem Description"
description: "How to resolve [problem] when using Coolify."
---

# Fix: Problem Description

## Problem

Clear description of the problem users experience.

## Cause

Explanation of why this happens.

## Solution

### Method 1: Quick Fix

```bash
# Commands to fix the issue
```

### Method 2: Alternative Fix

Step-by-step alternative solution.

## Prevention

How to avoid this issue in the future.

## Related Issues

- [Related Problem](/troubleshoot/related)
```

## Configuration Guide

For settings and configuration documentation:

```markdown
---
title: "Configuring X"
description: "Complete guide to configuring X in Coolify."
---

# Configuring X

## Overview

Brief explanation of X and why you'd configure it.

## Configuration Options

| Setting | Default | Description |
|---------|---------|-------------|
| `SETTING_A` | `value` | What it does |
| `SETTING_B` | `value` | What it does |

## Examples

### Basic Configuration

```yaml
setting: value
```

### Advanced Configuration

```yaml
setting1: value1
setting2: value2
nested:
  option: value
```

## Best Practices

- Best practice 1
- Best practice 2

## Troubleshooting

Common configuration issues and solutions.
```

## Knowledge Base Article

For conceptual explanations:

```markdown
---
title: "Understanding X"
description: "Learn about X and how it works in Coolify."
---

# Understanding X

## What is X?

Clear explanation of the concept.

## How It Works

Technical explanation with diagrams if helpful.

## Use Cases

- Use case 1
- Use case 2

## Best Practices

Recommendations for using X effectively.

## Further Reading

- [Related Topic](/knowledge-base/related)
- [External Resource](https://example.com?utm_source=coolify.io)
```

## Template Selection Guide

| Template | Use When |
|----------|----------|
| Step-by-Step Guide | Task requires sequential steps |
| Troubleshooting | Solving a specific problem |
| Configuration | Explaining settings/options |
| Knowledge Base | Conceptual explanation |

```

### SIDEBAR.md

```markdown
# Sidebar Configuration

How to add pages to the VitePress sidebar navigation.

## File Location

```
docs/.vitepress/config.mts
```

The sidebar configuration starts around **line 130**.

## Structure

```typescript
sidebar: [
  {
    text: 'Section Name',
    collapsed: true,  // Can be expanded/collapsed
    items: [
      { text: 'Page Title', link: '/section/page-slug' },
      { text: 'Another Page', link: '/section/another-page' },
    ]
  },
  // More sections...
]
```

## Adding a Page

1. Find the appropriate section in the sidebar array
2. Add a new item to the `items` array
3. Use the page's display title for `text`
4. Use the relative path (without `.md`) for `link`

### Example

Adding a new guide to Knowledge Base:

```typescript
{
  text: 'Knowledge Base',
  collapsed: true,
  items: [
    { text: 'Existing Guide', link: '/knowledge-base/existing' },
    { text: 'My New Guide', link: '/knowledge-base/docker/my-guide' },  // Added
  ]
}
```

## Nested Sections

For subdirectories, you can create nested sections:

```typescript
{
  text: 'Knowledge Base',
  collapsed: true,
  items: [
    {
      text: 'Docker',
      collapsed: true,
      items: [
        { text: 'Docker Basics', link: '/knowledge-base/docker/basics' },
        { text: 'Docker Compose', link: '/knowledge-base/docker/compose' },
      ]
    },
    {
      text: 'Server',
      collapsed: true,
      items: [
        { text: 'SSH Setup', link: '/knowledge-base/server/ssh' },
      ]
    }
  ]
}
```

## Link Format

- **Always** start with `/` (absolute from docs root)
- **Never** include `.md` extension
- **Never** include `/docs` prefix

| File Path | Sidebar Link |
|-----------|--------------|
| `docs/knowledge-base/guide.md` | `/knowledge-base/guide` |
| `docs/troubleshoot/apps/error.md` | `/troubleshoot/apps/error` |

## When Sidebar Update Is Optional

Some pages don't need sidebar entries:

- Pages linked from other pages but not primary navigation
- Supplementary content accessed via in-page links
- Index pages that redirect

## Verification

After updating:

1. Run `bun run dev`
2. Check sidebar shows new page
3. Click to verify link works
4. Check page renders correctly

```

### ../_shared/FRONTMATTER.md

```markdown
# Frontmatter Reference

Required and optional frontmatter fields for documentation pages.

## Required Fields

Every documentation page MUST have:

```yaml
---
title: "Page Title"
description: "SEO-friendly description (150-160 characters ideal)."
---
```

### Title Guidelines

- **Be specific**: "Deploying Laravel on Coolify" not "Laravel"
- **Include context**: Users should know what they'll learn
- **Keep concise**: Under 60 characters for SEO

### Description Guidelines

- **Summarize the page**: What will users learn or accomplish?
- **Include keywords**: Terms users might search for
- **Length**: 150-160 characters is ideal for search results

## Optional: Open Graph Image

Override the default social sharing image:

```yaml
---
title: "Page Title"
description: "Description here."
image: /docs/images/og/custom-og-image.png
---
```

### How Open Graph Works

VitePress automatically generates OG meta tags from frontmatter:

| Frontmatter | OG Tag | Fallback |
|-------------|--------|----------|
| `title` | `og:title` | Page heading or "Coolify Docs" |
| `description` | `og:description` | Default site description |
| `image` | `og:image` | `https://coolcdn.b-cdn.net/assets/coolify/og-image-docs.png` |

The same values are used for Twitter Card tags (`twitter:title`, etc.).

### Custom OG Images

For pages that benefit from custom social images (major features, key guides):

1. **Create image**: 1200×630px recommended (summary_large_image)
2. **Save to**: `docs/public/images/og/`
3. **Reference in frontmatter**: Use `/docs/images/og/filename.png`

**Note:** Relative paths are automatically converted to absolute URLs.

## Complete Example

```yaml
---
title: "How to Deploy WordPress on Coolify"
description: "Step-by-step guide to deploying WordPress with automatic SSL, backups, and one-click updates using Coolify."
image: /docs/images/og/wordpress-guide.png
---
```

## Validation Checklist

- [ ] `title` is present and specific
- [ ] `description` is present and descriptive
- [ ] Title under 60 characters (for SEO)
- [ ] Description 150-160 characters (for search results)
- [ ] Custom `image` only if page warrants it

```

### ../_shared/IMAGES.md

```markdown
# Image Guidelines

How to use images in Coolify documentation.

## Quick Reference

| Image Type | Syntax | When to Use |
|------------|--------|-------------|
| Logos/icons | `![Alt](/docs/images/path.svg)` | Small images, service logos |
| Screenshots | `<ZoomableImage src="/docs/images/path.webp" />` | UI screenshots, large images |
| Diagrams | Either (based on size) | Architecture diagrams, flowcharts |

## Standard Markdown Images

Use for **small images** that don't need zoom capability:

```markdown
![Service Name](/docs/images/services/service-logo.svg)
```

**Best for:**
- Service logos
- Small icons
- Badges and status indicators
- Simple inline graphics

## ZoomableImage Component

Use for **large images** users may want to examine closely:

```vue
<ZoomableImage src="/docs/images/section/screenshot.webp" alt="Description" />
```

**Best for:**
- Dashboard screenshots
- Configuration panels
- UI walkthroughs
- Any image with fine details

## File Paths

### Storage Location

```
docs/public/images/{section}/{filename}.{ext}
```

**Sections:**
- `services/` - Service logos and screenshots
- `get-started/` - Getting started guide images
- `applications/` - Application deployment screenshots
- `knowledge-base/` - KB article images
- `og/` - Open Graph social images

### In Documentation

```
/docs/images/{section}/{filename}.{ext}
```

**Note:** The `/public/` part is omitted - VitePress serves from `/docs/` directly.

## File Format Preferences

| Format | Use For | Notes |
|--------|---------|-------|
| SVG | Vector logos, icons | Best quality, smallest size |
| WebP | Screenshots, photos | Modern format, great compression |
| PNG | Logos with transparency | When SVG unavailable |
| JPEG | Never for logos | Avoid - no transparency, lossy |

## Optimization

Before adding images:

1. **Compress**: Use [Squoosh](https://squoosh.app/) or [SVGOMG](https://jakearchibald.github.io/svgomg/)
2. **Check size**: Keep under 100KB when possible
3. **Verify dimensions**: Screenshots max 1920px wide

## Naming Convention

```
{descriptive-name}-{type}.{ext}
```

**Examples:**
- `wordpress-logo.svg` (service logo)
- `deploy-button.webp` (UI screenshot)
- `architecture-diagram.svg` (diagram)

**Rules:**
- Lowercase only
- Hyphens for spaces
- Include type suffix (`-logo`, `-screenshot`, `-diagram`)
- Match actual file extension

## Common Mistakes

❌ **Don't:**
- Use external image URLs (GitHub raw, CDNs)
- Use `<ZoomableImage>` for small logos (unnecessary zoom)
- Use relative paths (`./images/...`)
- Forget alt text for accessibility

✅ **Do:**
- Download all images locally
- Use standard markdown for logos
- Use ZoomableImage for screenshots
- Start paths with `/docs/images/`
- Include descriptive alt text

```

### ../_shared/LINKS.md

```markdown
# Link Guidelines

How to format internal and external links in documentation.

## Internal Links

Use **absolute paths** from the docs root:

```markdown
[WordPress guide](/services/wordpress)
[Getting started](/get-started/introduction)
[SSH keys](/knowledge-base/server/openssh)
```

**Rules:**
- Always start with `/`
- No `.md` extension needed
- Use descriptive anchor text (not "click here")

### Section Paths

| Section | Path Pattern |
|---------|--------------|
| Services | `/services/{slug}` |
| Applications | `/applications/{framework}` |
| Databases | `/databases/{database}` |
| Knowledge Base | `/knowledge-base/{category}/{topic}` |
| Troubleshoot | `/troubleshoot/{issue}` |
| Get Started | `/get-started/{topic}` |

## External Links

Always add UTM tracking parameter:

```markdown
[Official WordPress docs](https://wordpress.org/documentation/?utm_source=coolify.io)
[GitHub repository](https://github.com/example/project?utm_source=coolify.io)
```

### UTM Format

Append `?utm_source=coolify.io` to all external URLs.

**If URL already has parameters:**
```markdown
[Link](https://example.com/page?tab=config&utm_source=coolify.io)
```

### External Link Styling

VitePress automatically adds external link indicators (↗). No manual decoration needed.

## Link Types

### Documentation Cross-References

```markdown
See the [deployment guide](/applications/laravel) for framework-specific instructions.

For more details, refer to [SSH configuration](/knowledge-base/server/openssh).
```

### Official Resources

```markdown
- [Official documentation](https://docs.example.com?utm_source=coolify.io)
- [GitHub repository](https://github.com/example/repo?utm_source=coolify.io)
- [Project website](https://example.com?utm_source=coolify.io)
```

### Coolify Resources

```markdown
- [Coolify Discord](https://discord.gg/coolify)
- [Coolify GitHub](https://github.com/coollabsio/coolify)
- [Coolify Changelog](https://coolify.io/changelog)
```

**Note:** Coolify's own resources don't need UTM parameters.

## Anchor Links

Link to specific sections within pages:

```markdown
[Configuration options](#configuration)
[Troubleshooting section](/services/wordpress#troubleshooting)
```

**Rules:**
- Use lowercase
- Replace spaces with hyphens
- Match the heading exactly

## Common Mistakes

❌ **Don't:**
- Use bare URLs without anchor text
- Forget UTM parameters on external links
- Use relative paths (`./other-page`)
- Use "click here" or "here" as anchor text

✅ **Do:**
- Use descriptive anchor text
- Add `?utm_source=coolify.io` to external URLs
- Use absolute paths starting with `/`
- Link to specific sections when relevant

```

### ../_shared/CONTAINERS.md

```markdown
# VitePress Containers

Callout containers for highlighting important information.

## Available Containers

### Tip

For helpful recommendations:

```markdown
::: tip
Helpful tips and recommendations.
:::
```

### Info

For additional context:

```markdown
::: info
Additional information or context.
:::
```

### Warning

For important prerequisites or cautions:

```markdown
::: warning
Important warnings or prerequisites.
:::
```

### Danger

For critical warnings:

```markdown
::: danger
Critical warnings about data loss or security.
:::
```

### Success

For confirmation messages:

```markdown
::: success
Success messages or confirmations.
:::
```

## Custom Titles

Add a custom title after the container type:

```markdown
::: warning Prerequisites
You must complete X before proceeding.
:::

::: tip Pro Tip
This advanced technique can save time.
:::

::: danger Data Loss Warning
This action cannot be undone.
:::
```

## When to Use Each Type

| Container | Use For |
|-----------|---------|
| `tip` | Best practices, shortcuts, recommendations |
| `info` | Background context, explanations, notes |
| `warning` | Prerequisites, cautions, important notes |
| `danger` | Data loss, security risks, breaking changes |
| `success` | Completed steps, confirmations |

## Examples in Context

### Prerequisites Section

```markdown
## Prerequisites

::: warning Required Setup
Before proceeding, ensure you have:
- SSH access to your server
- Docker installed
- A domain name configured
:::
```

### After a Risky Step

```markdown
## 3. Reset Database

::: danger
This will delete all existing data. Make sure you have a backup.
:::

```bash
coolify db:reset
```
```

### Helpful Tip

```markdown
## Configuration

::: tip
You can also set these values via environment variables for easier deployment.
:::
```

## Nesting Content

Containers can include any markdown:

```markdown
::: info Multiple Items
You can include:
- Bullet lists
- **Bold text**
- `code snippets`
- [Links](/path)
:::
```

```