How to migrate from djangocms-blog¶

This guide helps you migrate from djangocms-blog to djangocms-stories.

Pre-migration Checklist¶

Before starting the migration:

Backup your database - Create a full backup
Document customizations - Note any custom templates, fields, or modifications
Test environment - Perform migration in a staging environment first
Dependencies - Check for other packages that depend on djangocms-blog

Installation Steps¶

Uninstall djangocms-blog:
```
pip uninstall djangocms-blog
```
Install djangocms-stories:
```
pip install djangocms-stories
```

Add to INSTALLED_APPS (keep djangocms_blog for now):

INSTALLED_APPS = [
    # ... other apps
    'djangocms_blog',  # Keep temporarily
    'djangocms_stories',  # Add new
    # ... dependencies
]

Migrate data by running migrations:
```
python manage.py migrate djangocms_blog
python manage.py migrate djangocms_stories
```
Warning

The migration process will move existing data from djangocms-blog’s database table to the new djangocms-stories tables and delete the old tables. Be sure to have made a backup.

Remove djangocms_blog from INSTALLED_APPS:

INSTALLED_APPS = [
    # ... other apps
    'djangocms_stories',  # Keep new
    # ... dependencies
]

Template Migration¶

Update your templates to use the new namespace:

Rename template directories:

mv templates/djangocms_blog templates/djangocms_stories

Update template tags in templates:

# Old
{% load blog_tags %}

# New
{% load stories_tags %}

Update URL names:

# Old
{% url 'djangocms_blog:post-detail' slug=post.slug %}

# New
{% url 'djangocms_stories:post-detail' slug=post.slug %}

Settings Migration¶

Update your Django settings:

# Replace blog settings with stories equivalents

# Old
BLOG_PAGINATE_BY = 10
BLOG_USE_ABSTRACT = True

# New
STORIES_PAGINATE_BY = 10
STORIES_USE_ABSTRACT = True

URL Configuration¶

Normally, URL configurations are migrated automatically. Only if you manage your blog / stories URLs manually, update your URL patterns:

# Old
path('blog/', include('djangocms_blog.urls')),

# New
path('blog/', include('djangocms_stories.urls')),

Post-migration Steps¶

Test thoroughly - Verify all functionality works
Update internal links - Update any hardcoded URLs
Clean up - Remove old templates and unused code

Troubleshooting¶

Note

Community help is available on our Discord server.

Common issues and solutions:

Missing templates: Copy and rename your blog templates to stories
Broken URLs: Update all URL references and set up redirects
Custom fields: Recreate custom fields in the new models
Permissions: Review and update user permissions for the new app