adding-service-documentation

Add Service Documentation

This skill guides you through documenting a new service in the Coolify documentation repository.

When to Use This Skill

• Adding documentation for a new service from the Coolify repository
• Creating service pages with proper formatting and images
• Updating the services list component
• Following documentation standards for service pages

Quick Start Workflow

1. Identify the service from Coolify's GitHub repository (templates/compose/)
2. Extract metadata from the YAML template header
3. Download the logo from GitHub and save to docs/public/images/services/
4. Create documentation at docs/services/{service-slug}.md
5. Update services list in docs/.vitepress/theme/components/Services/List.vue
6. Update all services directory in docs/services/all.md
7. Test locally with bun run dev

File Structure

Coolify Repository (GitHub):
├── templates/compose/
│   └── service-name.yaml        # Service template with metadata
└── public/svgs/
    └── service-logo.svg          # Service logo

https://github.com/coollabsio/coolify/tree/main/templates/compose
https://github.com/coollabsio/coolify/tree/main/public/svgs

Documentation Repository:
├── docs/
│   ├── services/
│   │   ├── service-name.md       # Service documentation page
│   │   └── all.md                # All services directory (categorized list)
│   ├── public/images/services/
│   │   └── service-logo.svg      # Copied logo
│   └── .vitepress/theme/components/Services/
│       └── List.vue               # Services catalog (line ~261)

Required Files

Every service requires these 4 updates:

1. Service documentation (docs/services/{slug}.md)
2. Service logo (docs/public/images/services/{name}-logo.{ext})
3. List entry (in docs/.vitepress/theme/components/Services/List.vue)
4. All services directory (docs/services/all.md) — add entry alphabetically under the correct category

Detailed Instructions

Service-specific:

• METADATA.md - Extracting service info from YAML
• DOCUMENTATION.md - Writing service docs
• IMAGES.md - Service logo guidelines
• CATALOG.md - Updating the services list
• TEMPLATES.md - Documentation templates

Shared guidelines:

• FRONTMATTER.md - Title, description, Open Graph
• IMAGES.md - General image syntax
• LINKS.md - Internal and external link formatting
• CONTAINERS.md - VitePress callout containers

Important Rules

1. Download logos locally: NEVER use external image URLs - always download to docs/public/images/services/
2. Skip ignored services: If YAML has # ignore: true, don't document it
3. Images: Use ![alt](path) for logos; use <ZoomableImage> only for screenshots
4. Add UTM parameters: Append ?utm_source=coolify.io to all external links
5. Follow naming: Use lowercase, hyphenated slugs (e.g., my-service.md)
6. Alphabetical order: Insert services alphabetically in List.vue

Testing

# Start dev server
bun run dev

# Verify:
# - Service appears in list at http://localhost:5173/docs/services/
# - Logo displays correctly
# - Service page loads at /docs/services/{slug}
# - All links work
# - Category filter includes service

# Build for production
bun run build

Troubleshooting

Image not showing:

• Check path starts with /docs/images/services/ (not /public/)
• Verify file exists in docs/public/images/services/
• Confirm file extension matches

Service not in list:

• Verify entry added to services array in List.vue
• Check ignore: true is not set
• Ensure valid JavaScript syntax

Category missing:

• Check category name matches existing categories (case-sensitive)
• See CATALOG.md for full category list

Related Commands

• /new-services - Automated service documentation generator
• Check existing services for examples in docs/services/