This is an A/B testing plugin for Pelican. It allows you to encode
experiments in your templates and renders the experiment selected by
the AB_EXPERIMENT
environment variable. 'control' is the default
experiment name if AB_EXPERIMENT
is not specified!
To install:
pip install pelican-ab
Enable the plugin in pelicanconf.py
like this:
PLUGIN_PATHS = ['path/to/pelican-ab'] PLUGINS = ['pelican_ab']
PLUGIN_PATHS
can be a path relative to your settings file or an absolute
path. Alternatively, if plugins are in an importable path, you can omit
PLUGIN_PATHS
and list them:
PLUGINS = ['pelican_ab']
or you can import
the plugin directly and give the module name instead:
import pelican_ab PLUGINS = [pelican_ab]
The template syntax is provided by the jinja-ab extension which is automatically loaded:
{% experiment control %}This is the control{% endexperiment %} {% experiment v1 %}This is version 1{% endexperiment %}
Alternative syntax is also supported:
{% ab control %}This is the control{% endab %} {% ab v1 %}This is version 1{% endab %}
You can also mix the two tags in a single template:
{% experiment control %}This is the control{% endexperiment %} {% ab v1 %}This is version 1{% endab %}
Single and double quoted names are also supported!
For local development use the command:
AB_EXPERIMENT="xy" make regenerate
or:
AB_EXPERIMENT="xy" make html
together with make serve
to review the experiments.
When you are ready to publish them online use:
rm -rf output/ make github AB_EXPERIMENT="01" make github AB_EXPERIMENT="02" make github
See the section about DELETE_OUTPUT_DIRECTORY
for more info.
After encoding your experiments into the theme templates you can generate the resulting HTML files like this:
AB_EXPERIMENT="v1" make html
When rendering experiments the resulting HTML files are saved under
OUTPUT_PATH
plus the experiment name. For example 'output/v1', 'output/v2',
etc. The control experiments are rendered directly under OUTPUT_PATH
.
This plugin automatically updates the Content.url
and URLWrapper.url
class properties from Pelican so that things like {{ article.url }}
and {{ author.url }}
will point to URLs from the same experiment. In other words each experiment
produces its own HTML and URL structure, using the experiment name as
prefix. For example 'blog/about-me.html' becomes 'v1/blog/about-me.html'.
By default publishconf.py
has DELETE_OUTPUT_DIRECTORY
set to True
which causes pelican-ab to raise an exception. The problem is that you need to
execute make publish
or make github
for each experiment you'd like to
publish online. When DELETE_OUTPUT_DIRECTORY
is True the previous
contents will be deleted and ONLY that variation will be published!
This will break your website because everything will be gone!
- v0.2.4 (Dec 25th 2016)
- add more tests
- enable pylint during testing
- fix bad
super()
call
- v0.2.3 (Dec 13th 2016)
- rebuilt for Pelican v3.7.0 which now expects
Jinja2 extensions in the
JINJA_ENVIRONMENT
setting instead ofJINJA_EXTENSIONS
.
- rebuilt for Pelican v3.7.0 which now expects
Jinja2 extensions in the
- v0.2.2 (May 12th 2016)
- raise RuntimeError if
DELETE_OUTPUT_DIRECTORY
is set to True
- raise RuntimeError if
- v0.2.1 (May 11th 2016)
- updated README
- v0.2.0 (May 10th 2016)
- initial release
Source code and issue tracker are at https://github.com/MrSenko/pelican-ab
Mr. Senko provides commercial support for open source libraries, should you need it!