A/B testing plugin for Pelican
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
pelican_ab
tests
.gitignore
.travis.yml
LICENSE
README.rst
setup.py
test.sh

README.rst

Pelican A/B testing plugin

Build status

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!

How to test and publish experiments

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.

Output files

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'.

DELETE_OUTPUT_DIRECTORY

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!

CHANGELOG

  • 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 of JINJA_EXTENSIONS.
  • v0.2.2 (May 12th 2016)
    • raise RuntimeError if DELETE_OUTPUT_DIRECTORY is set to True
  • v0.2.1 (May 11th 2016)
    • updated README
  • v0.2.0 (May 10th 2016)
    • initial release

Contributing

Source code and issue tracker are at https://github.com/MrSenko/pelican-ab

Commercial support

Mr. Senko provides commercial support for open source libraries, should you need it!