kdeldycke / plumage

Plumage is a clean and tidy theme for Pelican, a static site generator.

I initially created this theme for my blog, but it is now generic enough to be used by anyone.

Features

• Standard Pelican views:

  Article	Categories	Tiered tag list
  Collapsable yearly archives	Tagged articles	Authors
  Faceted article browsing

• Projects template:

  Code showcase (source)	Videos showcase (source)	Themes showcase (source)

• Based on Bootstrap v4.

• Code syntax highlighting with 30+ styles.

• Site-wide static search via Tipue-search.

• Bare YouTube links in articles gets rendered as embedded videos:

  

• Direct link to edit articles on GitHub:

  

• Magnifying glass overlays on images and zoom:

  

• External assets (Bootstrap, Jquery, etc...) uses CDNjs .

• Disqus integration:

  

Plugins

Plumage has built-in support for the following plugins and extensions:

Installation

Install this theme using the develop branch of this Github repo.

If you're already using poetry to manage dependency of Pelican project, you need to run just

poetry add git+https://github.com/kdeldycke/plumage#develop

Or, can manually add the following line in the [tool.poetry.dependencies] section of the pyproject.toml file.

plumage = {git = "https://github.com/kdeldycke/plumage", rev = "develop"}

Once added, run poetry update to reflect this new dependency.

Note: If you haven't used poetry in the project yet, you need to do so before adding plumage. You can do that by first installing poetry on your system and then running poetry init inside the project folder.

Then, once you're done installing the plumage module, update your pelicanconf.py file to reference the module and requied extra plugins:

import plumage

THEME = plumage.get_path()

PLUGINS = [
    (…)
    "pelican.plugins.webassets",
]

On first run, Plumage will try to install Node.js package dependencies via the npm CLI:

$ poetry run pelican --verbose ./content
(…)
WARNING: postcss CLI not found.
-> Install Plumage's Node.js dependencies from (…)/plumage/package.json:
  |   {
  |     "name": "plumage-webassets-pipeline",
  |     "description": "Plumage depdencies for the webassets compilation pipeline.",
  |     "dependencies": {
  |       "postcss-cli": "^8.3.1"
  |     }
  |   }
  |

up to date, audited 96 packages in 984ms

found 0 vulnerabilities
-> postcss CLI found at (…)/plumage/node_modules/.bin/postcss
(…)

Settings

Plumage can be customized by adding these optionnal parameters to your pelicanconf.py file:

Most of these parameters are similar to notmyidea's (Pelican's default theme). For usage example, please have a look into my own pelicanconf.py .

The theme is also sensible to this list of standard Pelican parameters :

• ARCHIVES_SAVE_AS
• AUTHOR
• AUTHOR_SAVE_AS
• AUTHORS_SAVE_AS
• CATEGORIES_SAVE_AS
• CATEGORY_FEED_ATOM
• CATEGORY_FEED_RSS
• DEFAULT_LANG
• DEFAULT_PAGINATION
• DISPLAY_PAGES_ON_MENU
• DISPLAY_CATEGORIES_ON_MENU
• FEED_ALL_ATOM
• FEED_ALL_RSS
• FEED_ATOM
• FEED_DOMAIN
• FEED_RSS
• PAGINATION_PATTERNS
• SITENAME
• SITEURL
• TAG_FEED_ATOM
• TAG_FEED_RSS
• TAGS_SAVE_AS

Code Syntax Highlighting

There is two alternatives, all relying on Pygments syntax highlighter, sharing most features, with some differences:

Python Markdown CodeHilite

Just add this configuration to pelicanconf.py, which allows us to pass extra options to Pygments' HTML formatter:

MARKDOWN = {
    "extension_configs": {
        (…)
        "markdown.extensions.codehilite": {
            "css_class": "codehilite",  # Default
            "linenums": True,
            "linenos": "inline",
            "linespans": "coderow",
            "lineanchors": "L",
            "anchorlinenos": True,
            "wrapcode": True,
        },
        "markdown.extensions.fenced_code": {},
        (…)
    },
}

This will render this:

```{.shell-session hl_lines="8 11" linenostart="5" linenospecial="3" filename="~/code/foo.log"}
$ cat ./example.markdown
This is the content of the file:
→ java
→ rust
→ haskell
→ javascript

$ cat ./addendum.txt
This is extra content.

$ find ./ -iname "*.markdown" -print -exec bash -c 'cat ./addendum.txt >> "{}"' \;
./example.markdown
$ cat ./example.markdown
This is the content of the file:
→ java
→ rust
→ haskell
→ javascript

This is extra content.

```

Into this:

PyMdown Extensions' Highlight

Just add this configuration to your pelicanconf.py:

MARKDOWN = {
    "extension_configs": {
        (…)
        "pymdownx.highlight": {
            "linenums": True,
            "linenums_style": "pymdownx-inline",
        },
        "pymdownx.superfences": {},
        (…)
    },
}

This will render this:

```{.shell-session hl_lines="8 11" linenums="5 1 3" filename="~/code/foo.log"}
$ cat ./example.markdown
This is the content of the file:
→ java
→ rust
→ haskell
→ javascript

$ cat ./addendum.txt
This is extra content.

$ find ./ -iname "*.markdown" -print -exec bash -c 'cat ./addendum.txt >> "{}"' \;
./example.markdown
$ cat ./example.markdown
This is the content of the file:
→ java
→ rust
→ haskell
→ javascript

This is extra content.

```

Into this:

FAQ

How can I disable the zoom on images?

All images of an article are zoomable by default. You can deactivate the magnifying glass per-image by adding a noZoom CSS class. So instead of the following Markdown code:

![Image title](/folder/image.png)

You have to use the following template to deactivate the zoom of an image:

![Image title](/folder/image.png){: .noZoom}

Why is the search not working?

The tipue-search needs to be installed then have an additional template file registered in your pelicanconf.py.

There are two alternatives:

• update the TEMPLATE_PAGES variable:

  TEMPLATE_PAGES = {
      (…)
      "search.html": "search.html",
   }

• or DIRECT_TEMPLATES: (example):

  DIRECT_TEMPLATES = [(…), "search"]

License

This software is licensed under the GNU General Public License v2 or later (GPLv2+).

Copyright (C) 2012-2020 Kevin Deldycke and contributors. All Rights Reserved.

Third-party assets

The theme embed copies of some external softwares, scripts, libraries and artworks:

Tipue Search v7.1
Copyright (c) 2019 Tipue
Distributed under a MIT license
Source: https://web.archive.org/web/20200703134724/https://www.tipue.com/search/tipuesearch.zip

jQuery MGlass v1.1
Copyright (c) 2012 Younès El Biache
Distributed under a MIT license
Source: https://github.com/younes0/jQuery-MGlass

Fabric (Plaid)
Copyright (c) 2012 James Basoo
Distributed under a Creative Commons Attribution-ShareAlike 3.0 Unported license
Source: https://subtlepatterns.com/fabric-plaid/

Cream paper
Copyright (c) 2012 Devin Holmes
Distributed under a Creative Commons Attribution-ShareAlike 3.0 Unported license
Source: https://subtlepatterns.com/cream-paper/

Feather-alt icon v5.1.0
Copyright (c) 2020 Font Awesome project
Distributed under a Creative Commons Attribution 4.0 International license
Source: https://fontawesome.com/icons/feather-alt?style=solid

Macro shot of White Feather
Source: https://unsplash.com/photos/Sw7f58YJbc0