wagtail/docs/static_site_generation.rst

Generating a static site
========================

This document describes how to render your Wagtail site into static HTML files using `django medusa`_ and the 'wagtail.contrib.wagtailmedusa' module.


Installing django-medusa
~~~~~~~~~~~~~~~~~~~~~~~~

Firstly, install django medusa from pip:

.. code::

    pip install django-medusa


Then add 'django_medusa' and 'wagtail.contrib.wagtailmedusa' to INSTALLED_APPS:

.. code:: python

    INSTALLED_APPS = [
       ...
       'django_medusa',
       'wagtail.contrib.wagtailmedusa',
    ]


Replacing GET parameters with custom routing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pages which require GET parameters (eg, pagination) don't generate suitable filenames for generated HTML files so they need to be changed to use custom routing instead.

For example, lets say we have a Blog Index which uses pagination. We can override the 'route' method to make it respond on urls like '/page/1' and pass the page number through to the serve method:

.. code:: python

    class BlogIndex(Page):
        ...

        def serve(self, request, page=1):
            ...

        def route(self, request, path_components):
            if self.live and len(path_components) == 2 and path_components[0] == 'page':
                try:
                    return self.serve(request, page=int(path_components[1]))
                except (TypeError, ValueError):
                    pass

            return super(BlogIndex, self).route(request, path_components)


Rendering pages which use custom routing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For page types that override the route method, we need to let django medusa know which URLs it responds on. This is done by overriding the 'get_static_site_paths' method to make it yield one string per URL path.

For example, the BlogIndex above would need to yield one URL for each page of results:

.. code:: python

    def get_static_site_paths(self):
        # Get page count
        page_count = ...

        # Yield a path for each page
        for page in range(page_count):
            yield '/%d/' % (page + 1)

        # Yield from superclass
        for path in super(BlogIndex, self).get_static_site_paths():
            yield path


Rendering
~~~~~~~~~

To render a site, just run ``./manage.py staticsitegen``. This will render the entire website and place the HTML in a folder called 'medusa_output'. The static and media folders need to be copied into this folder manually after the rendering is complete.

To test, open the 'medusa_output' folder in a terminal and run ``python -m SimpleHTTPServer``.


.. _django medusa: https://github.com/mtigas/django-medusa