Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/textbook/bulrush
A Bulma-based Pelican blog theme; clean, flexible and responsive.
https://github.com/textbook/bulrush
blog-theme bulma flexbox pelican python
Last synced: 3 days ago
JSON representation
A Bulma-based Pelican blog theme; clean, flexible and responsive.
- Host: GitHub
- URL: https://github.com/textbook/bulrush
- Owner: textbook
- License: isc
- Created: 2016-11-30T20:24:02.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2024-09-05T14:54:03.000Z (2 months ago)
- Last Synced: 2024-09-24T15:18:05.089Z (about 2 months ago)
- Topics: blog-theme, bulma, flexbox, pelican, python
- Language: HTML
- Homepage: https://pypi.org/project/bulrush/
- Size: 1.24 MB
- Stars: 63
- Watchers: 6
- Forks: 22
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Bulrush
=======
A [Bulma][1]-based [Pelican][2] blog theme; clean, flexible and responsive.
![Screenshot - Bulrush at 1440px][13]
The icons are from [Font Awesome][3] by Dave Gandy. The pure HTML/CSS "Fork me
on GitHub" ribbon is based on [`github-fork-ribbon-css`][4] by Simon Whitaker; I
modified it to be flatter.
Features
--------
- [x] **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.
- [x] **Meta tagging functionality** - support for [Open Graph][5] and [Twitter
Cards][6] meta tags, giving enhanced display when sharing articles on social
media sites (**note**: *currently only available for [articles and pages][7]*).
- [x] **Printable layouts** - the navigation is hidden when printed, avoiding
wasted space.
- [x] **Custom styling** - additional CSS files can be included to customise
the default styling.
- [x] **Service integrations** - including Disqus, GitHub, Google Analytics
and MailChimp.
- [x] **PyPI package available** - so it can be `pip install`-ed.
- [x] **[Mermaid][25] integration** - so you can include generated diagrams.
Installation
------------
Bulrush is available via the [Python Package Index][22], so you can install it
with:
```bash
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:
```python
import bulrush
THEME = bulrush.PATH
JINJA_ENVIRONMENT = bulrush.ENVIRONMENT
JINJA_FILTERS = bulrush.FILTERS
```
### Other Requirements
You need to make the appropriate Pelican plugin, [`assets`][15], 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`:
```python
PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['assets']
```
**Note**: referencing the Pelican plugins in this way may have implications for
the license of your project. See https://github.com/textbook/bulrush/issues/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:
```python
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):
![Screenshot - Bulrush at 480px][11]
- 840 x 480px (tablet):
![Screenshot - Bulrush at 840px][12]
- 980 x 480px (desktop):
![Screenshot - Bulrush at 980px][10]
Settings
--------
As well as the [basic settings][14], 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][20] sign-up form; see details below. |
| `MERMAID` | Activate [Mermaid][25] 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`][17] 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.
![Screenshot - Social icons in sidebar][24]
### MailChimp Configuration
If you're using [MailChimp][20] 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][21]. Simply
look for the form action:
```html
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
If you set `MERMAID = True`, this will simply enable Mermaid with some default
settings:
```javascript
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][26]
you can pass a _dictionary_ instead. This will be shallowly merged into the
defaults:
```python
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`:
```python
# 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](http://blog.jonrshar.pe/)
- [Simon Says](https://simonsays.neocities.org/)
- [CodeRobot](http://coderobot.downley.net/)
If you'd like to be featured here (or are and would prefer not to be), feel
free to submit a [pull request][18].
[1]: http://bulma.io/
[2]: http://docs.getpelican.com/en/stable/
[3]: http://fontawesome.io/
[4]: https://github.com/simonwhitaker/github-fork-ribbon-css
[5]: http://ogp.me/
[6]: https://dev.twitter.com/cards/overview
[7]: http://docs.getpelican.com/en/3.6.3/content.html#articles-and-pages
[8]: http://jinja.pocoo.org/docs/dev/extensions/#with-statement
[9]: https://github.com/miracle2k/webassets/
[10]: ./screenshot-980px.png
[11]: ./screenshot-480px.png
[12]: ./screenshot-840px.png
[13]: ./screenshot-1440px.png
[14]: http://docs.getpelican.com/en/3.6.3/settings.html#basic-settings
[15]: https://github.com/getpelican/pelican-plugins/tree/master/assets
[17]: https://github.com/textbook/bulrush/blob/main/templates/social.html
[18]: https://help.github.com/articles/about-pull-requests/
[19]: http://kb.mailchimp.com/accounts/billing/add-or-remove-monkeyrewards
[20]: http://eepurl.com/cNv6Rb
[21]: http://kb.mailchimp.com/lists/signup-forms/add-a-signup-form-to-your-website
[22]: https://pypi.python.org/pypi/bulrush
[23]: http://fontawesome.io/icon/file-text-o/
[24]: ./screenshot-social.png
[25]: https://mermaid.js.org/
[26]: https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults