mirror of
https://github.com/wagtail/wagtail.git
synced 2024-12-01 11:41:20 +01:00
8c75baa271
Not actually needed unless you're setting a SENDFILE_BACKEND and in that case, you'll know you need it.
118 lines
3.9 KiB
ReStructuredText
118 lines
3.9 KiB
ReStructuredText
Static site generator
|
|
=====================
|
|
|
|
This document describes how to render your Wagtail site into static HTML files on your local file system, Amazon S3 or Google App Engine, using `django medusa`_ and the ``wagtail.contrib.wagtailmedusa`` module.
|
|
|
|
.. note::
|
|
|
|
An alternative module based on the `django-bakery`_ package is available as a third-party contribution: https://github.com/mhnbcu/wagtailbakery
|
|
|
|
Installing ``django-medusa``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
First, install ``django-medusa`` and ``django-sendfile`` from pip:
|
|
|
|
.. code::
|
|
|
|
pip install django-medusa django-sendfile
|
|
|
|
Then add ``django_medusa`` and ``wagtail.contrib.wagtailmedusa`` to ``INSTALLED_APPS``:
|
|
|
|
.. code:: python
|
|
|
|
INSTALLED_APPS = [
|
|
...
|
|
'django_medusa',
|
|
'wagtail.contrib.wagtailmedusa',
|
|
]
|
|
|
|
Define ``MEDUSA_RENDERER_CLASS``, ``MEDUSA_DEPLOY_DIR`` and ``SENDFILE_BACKEND`` in settings:
|
|
|
|
.. code:: python
|
|
|
|
MEDUSA_RENDERER_CLASS = 'django_medusa.renderers.DiskStaticSiteRenderer'
|
|
MEDUSA_DEPLOY_DIR = os.path.join(BASE_DIR, 'build')
|
|
SENDFILE_BACKEND = 'sendfile.backends.simple'
|
|
|
|
|
|
Rendering
|
|
~~~~~~~~~
|
|
|
|
To render a site, 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. This feature inherits ``django-medusa``'s ability to render your static site to Amazon S3 or Google App Engine; see the `medusa docs <https://github.com/mtigas/django-medusa/blob/master/README.markdown>`_ for configuration details.
|
|
|
|
To test, open the ``medusa_output`` folder in a terminal and run ``python -m SimpleHTTPServer``.
|
|
|
|
|
|
Advanced topics
|
|
~~~~~~~~~~~~~~~
|
|
|
|
GET parameters
|
|
--------------
|
|
|
|
Pages which require GET parameters (e.g. for pagination) don't generate a suitable file name for the generated HTML files.
|
|
|
|
Wagtail provides a mixin (``wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin``) which allows you to embed a Django URL configuration into a page. This allows you to give the subpages a URL like ``/page/1/`` which work well with static site generation.
|
|
|
|
|
|
Example:
|
|
|
|
.. code:: python
|
|
|
|
from wagtail.contrib.wagtailroutablepage.models import RoutablePageMixin
|
|
|
|
|
|
class BlogIndex(Page, RoutablePageMixin):
|
|
...
|
|
|
|
subpage_urls = (
|
|
url(r'^$', 'serve_page', {'page': 1}),
|
|
url(r'^page/(?P<page>\d+)/$', 'serve_page', name='page'),
|
|
)
|
|
|
|
def serve_page(self, request, page=1):
|
|
...
|
|
|
|
|
|
Then in the template, you can use the ``{% routablepageurl %}`` tag to link between the pages:
|
|
|
|
.. code:: html+Django
|
|
|
|
{% load wagtailroutablepage_tags %}
|
|
|
|
{% if results.has_previous %}
|
|
<a href="{% routablepageurl self 'page' results.previous_page_number %}">Next page</a>
|
|
{% else %}
|
|
|
|
{% if results.has_next %}
|
|
<a href="{% routablepageurl self 'page' results.next_page_number %}">Next page</a>
|
|
{% else %}
|
|
|
|
|
|
Next, you have to tell the ``wagtailmedusa`` module about your custom routing...
|
|
|
|
|
|
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
|
|
|
|
|
|
.. _django medusa: https://github.com/mtigas/django-medusa
|
|
.. _django-bakery: https://github.com/datadesk/django-bakery
|