renaming-services

Rename Service Documentation

This skill guides you through renaming a service in the Coolify documentation, ensuring all references are updated correctly.

When to Use This Skill

• Service name changed in the Coolify repository
• Fixing incorrect service naming (e.g., camelCase to kebab-case)
• Consolidating duplicate service documentation
• Correcting typos in service slugs

Critical: Four Locations Must Be Updated

When renaming a service, you MUST update all four locations:

1. Documentation file (docs/services/)
2. Services list (docs/.vitepress/theme/components/Services/List.vue)
3. All services directory (docs/services/all.md)
4. Nginx redirects (nginx/redirects.conf)

Failing to update all four will cause broken links or 404 errors.

Step-by-Step Process

1. Rename the Documentation File

# Rename the markdown file
git mv docs/services/old-name.md docs/services/new-name.md

Naming rules:

• Use lowercase only
• Use hyphens for spaces (kebab-case)
• Match the service name from service-templates-latest.json
• Don't use camelCase even if the JSON does (e.g., denoKV → denokv.md)

2. Update the Services List

Edit docs/.vitepress/theme/components/Services/List.vue:

// Find the service entry and update the slug
{
    name: 'Service Name',
    slug: 'new-name',  // ← Change from 'old-name'
    icon: '/docs/images/services/service-logo.svg',
    description: 'Service description',
    category: 'Category'
},

3. Add Nginx Redirects

Add redirect rules to nginx/redirects.conf:

# Redirect old service URL to new URL
location = /docs/services/old-name { return 301 /docs/services/new-name; }

# Also redirect legacy knowledge-base path if it existed
location = /knowledge-base/services/old-name { return 301 /docs/services/new-name; }

Important: Keep redirects even for deleted pages to prevent 404 errors from search engines and bookmarks.

4. Update All Services Directory

Edit docs/services/all.md and update the service entry under its category:

- [New Service Name](/services/new-name) - Service description

5. Update Internal Links

Search for any internal links referencing the old name:

# Search for references to the old service name
grep -r "old-name" docs/

Update any found references in other documentation files.

6. Rename Logo File (If Needed)

If the logo filename also needs updating:

# Rename the logo
git mv docs/public/images/services/old-name-logo.svg docs/public/images/services/new-name-logo.svg

Then update the icon path in List.vue.

Verification Checklist

After renaming, verify:

• New file exists: docs/services/new-name.md
• Old file removed or redirected
• List.vue slug matches new filename
• List.vue icon path is correct
• Entry updated in docs/services/all.md
• Redirect added to nginx/redirects.conf
• No broken internal links (run grep -r "old-name" docs/)
• Service appears correctly at http://localhost:5173/docs/services/new-name
• Old URL redirects to new URL

Common Scenarios

Fixing camelCase to kebab-case

When the Coolify JSON uses camelCase but docs should use lowercase:

• denoKV → denokv.md
• homeAssistant → home-assistant.md

Adding Version Numbers

When Coolify adds version-specific services:

• mautic.md → mautic5.md (if JSON specifies mautic5)

Consolidating Names

When compound names are required:

• ente.md → ente-photos.md (if JSON specifies ente-photos)

Troubleshooting

Service shows 404

• Check if redirect is in nginx/redirects.conf
• Verify slug in List.vue matches filename
• Ensure markdown file exists

Old URL still works without redirect

• Nginx config may need reload
• Check redirect syntax in redirects.conf

Search engines still show old URL

• Redirects are working correctly (301 tells search engines to update)
• Takes time for search engines to re-crawl

Related Skills

• adding-service-documentation - For creating new service docs
• disabling-services - For hiding deprecated services