Setup

If you’re starting from a Django project without Wagtail integration and you want to add a blog site to your project, please follow the steps outlined under Standalone blog app. If you are already using Wagtail, refer to Installation on top of Wagtail.

Standalone blog app

1. Install Puput and its dependencies via pip install puput.

2. Append PUPUT_APPS to INSTALLED_APPS in your settings.

from puput import PUPUT_APPS

INSTALLED_APPS += PUPUT_APPS

This includes Puput, Wagtail’s apps and certain third-party dependencies. If you are already referencing one of these apps in your INSTALLED_APPS list, please include the following apps manually in order to avoid app collisions:

INSTALLED_APPS = (
    ...
    'wagtail.contrib.legacy.richtext',
    'wagtail',
    'wagtail.admin',
    'wagtail.documents',
    'wagtail.snippets',
    'wagtail.users',
    'wagtail.images',
    'wagtail.embeds',
    'wagtail.search',
    'wagtail.sites',
    'wagtail.contrib.redirects',
    'wagtail.contrib.forms',
    'wagtail.contrib.sitemaps',
    'wagtail.contrib.routable_page',
    'taggit',
    'modelcluster',
    'puput',
)

3. Add Wagtail’s required middleware classes to MIDDLEWARE_CLASSES in your Django settings.

MIDDLEWARE = [
    ...
    'wagtail.contrib.redirects.middleware.RedirectMiddleware',
]

4. Add the request context processor to the TEMPLATE_CONTEXT_PROCESSORS structure in your Django settings.

TEMPLATES = [
    {
        ...
        "OPTIONS": {
            "context_processors": [
                ...
                "django.template.context_processors.request"
            ]
        }
    }
]

5. Set the WAGTAIL_SITE_NAME variable to the name of your site in your Django settings.

WAGTAIL_SITE_NAME = 'Puput blog'

6. Set the WAGTAILADMIN_BASE_URL variable to the base url of your site in your Django settings.

WAGTAILADMIN_BASE_URL = 'http://localhost:8000/'

7. Configure the MEDIA_ROOT and MEDIA_URL settings as described in the Wagtail Docs.

MEDIA_ROOT = os.path.join(PROJECT_ROOT, 'media')
MEDIA_URL = '/media/'

8. Place Puput’s URLs at the bottom of the urlpatterns. It also includes Wagtail’s URLs.

urlpatterns = [
    ...
    path(r'', include('puput.urls')),
]

9. To make your Django project serve your media files (e.g. things you upload via the admin) during development, don’t forget to add this to your urlpatterns:

from django.conf import settings
from django.conf.urls import url

if settings.DEBUG:
    import os
    from django.conf.urls.static import static
    from django.contrib.staticfiles.urls import staticfiles_urlpatterns
    from django.views.generic.base import RedirectView

    urlpatterns += staticfiles_urlpatterns() # tell gunicorn where static files are in dev mode
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
    urlpatterns += static(settings.MEDIA_URL + 'images/', document_root=os.path.join(settings.MEDIA_ROOT, 'images'))
    urlpatterns += [
        path(r'favicon\.ico', RedirectView.as_view(url=settings.STATIC_URL + 'myapp/images/favicon.ico')),
    ]

10. Run python manage.py migrate and python manage.py puput_initial_data to load initial data to start a blog site.

11. Open your browser at http://127.0.0.1:8000/blog/ to view your blog home page. Go to http://127.0.0.1:8000/blog_admin/ to view the admin site and edit your content.

Installation on top of Wagtail

0. This assumes that you have Wagtail >= 5.2 installed and you can access /admin; if this is not the case or you would like to use a newer version of Wagtail than is in the dependencies of puput, follow the steps below in a python venv:

pip install --upgrade pip
pip install wheel
pip install wagtail django-el-pagination
pip install --no-deps puput
wagtail start mysite
cd mysite
python manage.py migrate
python manage.py createsuperuser

1. If you haven’t already, install Puput and its dependencies via pip install puput.

2. In your Django settings (most commonly settings/base.py inside the wagtail directory), add the following to the INSTALLED_APPS following the wagtail section:

'wagtail.contrib.sitemaps',
'wagtail.contrib.routable_page',
'puput',

3. In the same file, also add the line PUPUT_AS_PLUGIN = True to the very bottom

4. In the same folder, add to urls.py near the top from puput import urls as puput_urls and just above url(r'', include(wagtail_urls)), add url(r'',include(puput_urls)),

5. Run python manage.py migrate followed by python manage.py runserver 0:8000 to start the server

6. To create a Puput blog navigate to the Wagtail admin interface at 127.0.0.1:8000/admin and create a new child page of type Blog. Every blog post is then created as a child of this blog.

Docker

If you want to run Puput in a Docker container please visit docker-puput for detailed instructions.