Skip to content

Latest commit

 

History

History
186 lines (128 loc) · 7.8 KB

README.md

File metadata and controls

186 lines (128 loc) · 7.8 KB
Raw

Wagtail-bakery

A set of helpers for baking your Django Wagtail site out as flat files.

License: MIT Build Status Version Monthly downloads

Wagtail-bakery is built on top of Django bakery. Please read their documentation for detailed configuration and how to build default Django flat files. Yes. Wagtail-bakery is not limited to build Wagtail pages specifically, mixed content is possible!

Links

Security

We take the security of Wagtail, and related packages we maintain, seriously. If you have found a security issue with any of our projects please email us at [email protected] so we can work together to find and patch the issue. We appreciate responsible disclosure with any security related issues, so please contact us first before creating a GitHub issue.

If you want to send an encrypted email (optional), the public key ID for [email protected] is 0xbed227b4daf93ff9, and this public key is available from most commonly-used keyservers.

Features

  • Single management command that will build your Wagtail site out as flat files
  • Support for multisite, theming and multilingual setup
  • Support for i18n_patterns
  • Support for generating a static API
  • Ready to use Wagtail Buildable views to build all your (un)published pages at once (no extra code required!)

Supported Versions

  • Python 3.8 - 3.12
  • Django 4.2 - 5.0
  • Wagtail >= 5.2

We aim to support the Wagtail versions as supported by Wagtail (current LTS, current stable).

Django/Wagtail combinations as supported by Wagtail (for the Wagtail versions as defined above).

Browser support

We align our browser support targets with that of Wagtail. Have a look at the official documentation.

Installation

pip install wagtail-bakery

Add bakery and wagtailbakery to your INSTALLED_APPS setting.

INSTALLED_APPS = (
    # ...
    'bakery',
    'wagtailbakery',
)

Configuration

Define whether you want to build multiple sites or the default site (see examples for impact on directory output), by default this settings is False.

BAKERY_MULTISITE = True

Add the build directory where you want to be the site be built as flat files.

BUILD_DIR = '/tmp/build/'

As you may know with Django bakery, the trickiest part is to make your current models/pages buildable with Buildable views. As Django Wagtail uses only the Page model at their lowest level, you can use at least one of the already present Buildable views provided by Wagtail bakery.

Build all published public pages (use for production).

BAKERY_VIEWS = (
	'wagtailbakery.views.AllPublishedPagesView',
)

Build all published and unpublished public pages (use for staging/acceptance).

BAKERY_VIEWS = (
	'wagtailbakery.views.AllPagesView',
)

To build static JSON files representing your site's API, use the following views:

BAKERY_VIEWS = (
	'wagtailbakery.api_views.PagesAPIDetailView',
	'wagtailbakery.api_views.PagesAPIListingView',
	'wagtailbakery.api_views.TypedPagesAPIListingView',
)

The API views use Wagtail's V2 API module. To configure the data that is rendered by these views, please refer to Wagtail's V2 API configuration guide.

Usage

Build the site out as flat files by running the build management command.

manage.py build

If you want to check how your static website will look, use the buildserver command after you have build your static files once.

manage.py buildserver

Examples

In the examples directory you can find a Wagtail setup with fixtures for a single site as well as a multisite setup.

Create a virtualenv and go to one of the examples, you can use the Make command to install all requirements, load fixtures and run the server.

As described in the usage section, use manage.py build to build out the example as static files.

Build output with BAKERY_MULTISITE=True:

build/example.com/index.html
build/example.com/about/index.html
build/example.com/blog/index.html
build/example.com/blog/example/index.html
build/static/

Build output with BAKERY_MULTISITE=False (default):

build/index.html
build/about/index.html
build/blog/index.html
build/blog/example/index.html
build/static/

Troubleshooting

For issues please submit an issue on GitHub.

Development

Which version combinations to include in Github Actions test matrix?

In order to keep for CI build time from growing out of control, not all Python/Django/Wagtail combinations will be tested.

Test as follow:

  • All supported Django/Wagtail combinations with the latest supported Python version.
  • The latest supported Django/Wagtail combination for the remaining Python versions.

Releases

  1. Create a new branch (e.g. release/1.1.3) for the release of the new version.
  2. Update the version number in setup.py following Semantic Versioning.
  3. Update CHANGELOG.md.
  4. On GitHub, create a pull request and squash merge it.
  5. On GitHub, if this is a minor release bump (for example 1.1.0 or 1.2.0 but not 1.1.1, 1.2.3), create a stable/1.1.x branch from main.
  6. (Optional) Publish to TestPyPI if you need to verify anything:
    1. Create and push a tag following the pattern X.Y.Z.devN (for example 1.1.3.dev1).
    2. Follow the action progress for the Publish to TestPyPI workflow.
    3. Check the result on TestPyPI: wagtail-bakery.
  7. Publish to PyPI:
    1. Create and push a tag following PEP 440 – Version Identification Specification (for example 1.1.3 or 1.1.3rc1), except for the .devN suffix used for testing (see Publish to TestPyPI step above)
    2. Follow the action progress for the Publish to PyPI workflow
    3. Check the result on PyPI: wagtail-bakery
  8. On GitHub, create a release and a tag for the new version.

Credits

Thanks to @mhnbcu for bringing this idea up initially, and Django Bakery for providing the initial bakery package.

Thanks to all the contributors for their help.