README.md

Bulrush

A Bulma-based Pelican blog theme; clean, flexible and responsive.

The icons are from Font Awesome by Dave Gandy. The pure HTML/CSS "Fork me on GitHub" ribbon is based on github-fork-ribbon-css by Simon Whitaker; I modified it to be flatter.

Features

• Responsive design - four column layout on desktop (≥980px), three column on tablet (≥769px), single column on mobile. Tabbed navigation bar collapses into drop-down "burger menu" on mobile.

• Meta tagging functionality - support for Open Graph and Twitter Cards meta tags, giving enhanced display when sharing articles on social media sites (note: currently only available for articles and pages).

• Printable layouts - the navigation is hidden when printed, avoiding wasted space.

• Custom styling - additional CSS files can be included to customise the default styling.

• Service integrations - including Disqus, GitHub, Google Analytics and MailChimp.

• PyPI package available - so it can be pip install-ed.

• Mermaid integration - so you can include generated diagrams.

Installation

Bulrush is available via the Python Package Index, so you can install it with:

pip install bulrush

The main exports from the module are:

• PATH: the path to the theme;
• FILTERS: the additional Jinja filters used by the theme; and
• ENVIRONMENT: the Jinja environment required by the theme.

You can use them in your pelicanconf.py as follows:

import bulrush

THEME = bulrush.PATH
JINJA_ENVIRONMENT = bulrush.ENVIRONMENT
JINJA_FILTERS = bulrush.FILTERS

Other Requirements

You need to make the appropriate Pelican plugin, assets, available. One way of achieving this is to make the pelican-plugin repository a submodule of your site, then you can add to your pelicanconf.py:

PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['assets']

Note: referencing the Pelican plugins in this way may have implications for the license of your project. See #17.

Alternative

If you don't want to install the theme from PyPI you can simply give Pelican a relative path to the inner bulrush/ directory. For example, add bulrush as a submodule and set:

THEME = 'bulrush/bulrush'

In this case you will need to configure the environment and filters yourself and ensure that webassets is installed from PyPI.

Additional Screenshots

• 480 x 480px (mobile):

  

• 840 x 480px (tablet):

  

• 980 x 480px (desktop):

  

Settings

As well as the basic settings, Bulrush supports the following options in your pelicanconf.py:

Setting name	What does it do?
BULRUSH_SHOW_SUMMARY	A boolean, whether to show a summary rather than full article on index, category and tag pages. Defaults to False.
DISQUS_SITENAME	Enables Disqus comments. Note that you should set up the full Comment Count Link, as no additional text is applied.
GITHUB_URL	Enables the "Fork me on GitHub" ribbon.
GOOGLE_ANALYTICS	Set to 'UA-XXXX-YYYY' to activate Google Analytics.
LICENSE	A string or dictionary describing the license for the site; see details below.
LINKS	A list of tuples ('Title', 'URL') for links to appear in the "blogroll" section of the sidebar.
MAILCHIMP	Configure to activate a MailChimp sign-up form; see details below.
MERMAID	Activate Mermaid diagram support; see details below.
MENUITEMS	A list of tuples ('Title', 'URL') for items to appear in the tabbed navigation.
SITESUBTITLE	A subtitle to appear in the header.
SOCIAL	A list of tuples ('Title', 'URL') to appear in the "social" section of the sidebar.
TWITTER_USERNAME	Enables Twitter meta-tags in the article and page headers.

If DISPLAY_CATEGORIES_ON_MENU is omitted or set explicitly to True, the categories are shown in the tabbed navigation with any MENUITEMS. If DISPLAY_PAGES_ON_MENU is omitted or set explicitly to True, they are listed in the sidebar with any SOCIAL or other LINKS.

Social Links

Appropriate icons are provided in the sidebar for a range of sites in the SOCIAL link list. Have a look in social.html to see which titles this applies to. If none of the sites are a match, then:

• if the second, URL element in the tuple starts with 'mailto:', an envelope icon is used; otherwise
• a globe icon is used.

MailChimp Configuration

If you're using MailChimp to handle a mailing list for your blog, you can configure a subscription form in the sidebar. You need to set three values to enable this, which you can get from the signup form creator. Simply look for the form action:

<form action="//user.region.list-manage.com/subscribe/post?u=abc123&amp;id=def456" ...

and extract the relevant sections:

MAILCHIMP = dict(
    domain='user.region.list-manage.com',
    user_id='abc123',
    list_id='def456',
    validation=True,  # enable jQuery validation
)

If you set validation=False (or leave it out entirely) you will reduce the page load (as it won't need 140KB of JavaScript) but won't get inline form submission or email validation.

You can also add rewards_url, providing your unique MonkeyRewards URL, to enable a "Powered by MailChimp" link.

License Settings

You can provide one of two options to specify the license for your content:

• License name (str): The name of the license to display. Unless otherwise specified, a default icon (file-text-o) will be used and the entry will link to the current page.

  Creative Commons license names (e.g. 'CC BY-SA 4.0') are automatically recognised and an appropriate icon and link are generated.

• License definition (dict): A dictionary specifying the name, url and optional icon (must be a Font Awesome icon name, default is file-text-o).

The license details will be displayed at the bottom of the sidebar on every page.

Mermaid Configuration

Enables Mermaid diagram generation on your site, allowing diagrams to be written in a Markdown-ish syntax. Simply wrap the code in a pre element with the mermaid class:

<pre class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</pre>

If you set MERMAID = True, this will simply enable Mermaid with some default settings:

  const defaults = {
    securityLevel: "loose",
    theme: "default",
    themeVariables: {
      fontFamily: 'BlinkMacSystemFont, -apple-system, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
    },
  };

To override these settings, or any of Mermaid's own default configuration you can pass a dictionary instead. This will be shallowly merged into the defaults:

MERMAID = dict(
    securityLevel="strict",
    theme="forest",  # disables fontFamily override
)

Custom Styling

If any of the entries in EXTRA_PATH_METADATA have 'path's ending with '.css' they will be included in the base template, allowing the site style to be overridden as required. For example, in your pelicanconf.py:

# Static files
STATIC_PATHS = [
    'extra',
    ...
]
EXTRA_PATH_METADATA = {
    'extra/custom.css': {'path': 'custom.css'},
    ...
}

In use

Here are few current users of Bulrush (or modified versions of it):

• textbook
• Simon Says
• CodeRobot

If you'd like to be featured here (or are and would prefer not to be), feel free to submit a pull request.