2014-05-20 10:17:49 +00:00
Generating a static site
========================
2015-04-19 09:53:34 +00:00
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.
2014-05-20 10:17:49 +00:00
2015-02-17 16:33:53 +00:00
.. note ::
An alternative module based on the `django-bakery`_ package is available as a third-party contribution: https://github.com/mhnbcu/wagtailbakery
2014-05-20 10:17:49 +00:00
2015-02-19 17:08:23 +00:00
Installing `` django-medusa ``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2014-05-20 10:17:49 +00:00
2015-03-04 10:53:36 +00:00
First, install `` django-medusa `` from pip:
2014-05-20 10:17:49 +00:00
.. code ::
pip install django-medusa
2014-05-22 16:51:50 +00:00
Then add `` django_medusa `` and `` wagtail.contrib.wagtailmedusa `` to `` INSTALLED_APPS `` :
2014-05-20 10:17:49 +00:00
.. code :: python
INSTALLED_APPS = [
...
'django_medusa',
'wagtail.contrib.wagtailmedusa',
]
2015-04-16 09:56:29 +00:00
Define `` MEDUSA_RENDERER_CLASS `` and `` MEDUSA_DEPLOY_DIR `` in settings:
.. code :: python
MEDUSA_RENDERER_CLASS = 'django_medusa.renderers.DiskStaticSiteRenderer'
MEDUSA_DEPLOY_DIR = os.path.join(BASE_DIR, 'build')
2014-05-20 10:17:49 +00:00
2014-07-03 11:53:11 +00:00
Rendering
~~~~~~~~~
2015-04-17 22:05:08 +00:00
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.
2014-07-03 11:53:11 +00:00
2015-04-17 22:05:08 +00:00
To test, open the `` medusa_output `` folder in a terminal and run `` python -m SimpleHTTPServer `` .
2014-07-03 11:53:11 +00:00
Advanced topics
~~~~~~~~~~~~~~~
2015-02-19 17:25:24 +00:00
GET parameters
--------------
2014-05-20 10:17:49 +00:00
2015-02-19 17:25:24 +00:00
Pages which require GET parameters (e.g. for pagination) don't generate suitable filenames for generated HTML files.
2014-05-20 10:17:49 +00:00
2015-04-17 22:05:08 +00:00
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.
2015-02-19 17:25:24 +00:00
Example:
2014-05-20 10:17:49 +00:00
.. code :: python
2015-02-19 17:25:24 +00:00
from wagtail.contrib.wagtailroutablepage.models import RoutablePageMixin
2014-07-04 17:24:01 +00:00
2015-02-19 17:25:24 +00:00
class BlogIndex(Page, RoutablePageMixin):
2014-05-20 10:17:49 +00:00
...
2015-02-19 17:25:24 +00:00
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):
2014-05-20 10:17:49 +00:00
...
2015-02-19 17:25:24 +00:00
Then in the template, you can use the `` {% routablepageurl %} `` tag to link between the pages:
2015-02-19 23:46:52 +00:00
.. code :: html+Django
2015-02-19 17:25:24 +00:00
{% 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...
2014-05-20 10:17:49 +00:00
Rendering pages which use custom routing
2014-07-03 11:53:11 +00:00
----------------------------------------
2014-05-20 10:17:49 +00:00
2015-04-17 22:05:08 +00:00
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.
2014-05-20 10:17:49 +00:00
For example, the BlogIndex above would need to yield one URL for each page of results:
.. code :: python
2014-05-20 11:39:23 +00:00
def get_static_site_paths(self):
2014-05-20 10:17:49 +00:00
# Get page count
page_count = ...
# Yield a path for each page
for page in range(page_count):
yield '/%d/' % (page + 1)
# Yield from superclass
2014-05-20 11:39:23 +00:00
for path in super(BlogIndex, self).get_static_site_paths():
2014-05-20 10:17:49 +00:00
yield path
.. _django medusa: https://github.com/mtigas/django-medusa
2015-02-19 23:46:52 +00:00
.. _django-bakery: https://github.com/datadesk/django-bakery