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.

• Standard Pelican views:

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

• Projects template:

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

• Based on Bootstrap v5.

• Code syntax highlighting with 30+ styles.

• Site-wide static search via Stork.

• 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, …) relies on CDNjs.

• Disqus integration:

  

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

$ python -m pip install uv
$ uv venv
$ source .venv/bin/activate
$ uv pip install .

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

import plumage

THEME = plumage.get_path()

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

$ uv 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 dependencies 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
(…)

Plumage can be customized by adding these optional 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

Syntax highlighting is produced by Pygments.

See MyST Markdown code syntax for more details.

TODO: document all kind customization below

The theme does not try to implements tricks and optimization beyond reasonable efforts.

This was attempted in the past which limited success. That's because it is hard to find up-to-date and maintained projects in the Python ecosystem.

Instead, I advise relying on external all-in-one optimization tools like Jampack.

After a build, just call it on the generated static content like so:

$ npx @divriots/jampack ./output

The official Pelican's search plugin needs to be installed.

TODO: Activate search field automaticcaly if the plugin is present.

If you need to work both on the content of your website and the theme, you need to:

• Get a local copy of the theme outside your website virtualenv:

  $ cd ..
  $ git clone https://github.com/kdeldycke/plumage.git
  $ cd ./my-pelican-website
  

• Change the plumage dependency in you website's pyproject.toml from:

  dependencies = [
      ...
      "plumage <anything>",
      ...
  ]

  To:

  dependencies = [
      ...
      "plumage",
      ...
  ]

• Also add this new section in the same pyproject.toml, to force uv to pick up the latest local copy:

  [tool.uv.sources]
  plumage = { path = "../plumage", editable = true }

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

Copyright © 2012-2024 Kevin Deldycke and contributors.

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

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

Cream paper
Copyright © 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 © 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