Skip to content
forked from kdeldycke/plumage

🎨 Theme for Pelican, the static site generator.

License

Notifications You must be signed in to change notification settings

kmonsoor/plumage

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Plumage, a Pelican theme

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:

    Plumage article view Plumage categories view Plumage tiered tag list view
    Article Categories Tiered tag list
    Plumage archive view Plumage tag view Plumage authors view
    Collapsable yearly archives Tagged articles Authors
    Plumage archive view
    Faceted article browsing
  • Projects template:

    Plumage projects: code showcase Plumage projects: videos showcase Plumage projects: themes showcase
    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:

    Plumage YouTube link

  • Direct link to edit articles on GitHub:

    Plumage GitHub edit link

  • Magnifying glass overlays on images and zoom:

    Plumage image magnifying glass Plumage image zoom

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

  • Disqus integration:

    Plumage disqus comments

Plugins

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

Plugin name Type Status Notes
pelican-image-process Pelican plugin Optional Embed a hack to fix parsing of external images.
pelican-neighbors Pelican plugin Optional
pelican-related-posts Pelican plugin Optional
pelican-similar-posts Pelican plugin Optional
pelican-tipue-search Pelican plugin Optional
pelican-webassets Pelican plugin Required
markdown.extensions.admonition Markdown extension Optional Re-style admonitions into alerts.
markdown.extensions.codehilite Markdown extension Optional Style highlighted code with Pygment style.
markdown.extensions.toc Markdown extension Optional Adds permalink anchors to article's subtitles.
pymdownx.emoji Markdown extension Optional Style emojione set for proper integration into text.
pymdownx.highlight Markdown extension Optional Style highlighted code with Pygment style.
typogrify Pelican builtin Optional Style ampersands.

Installation

This package is available on PyPi, so you can install the latest stable release and its dependencies with a simple pip call:

$ pip install plumage

Then, update your pelicanconf.py file, to reference the module and 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:

Setting name Default value Description
ARTICLE_EDIT_LINK Generate an edit link besides each article. Can use %(slug)s to include dynamic article's slug in the link.
CODE_STYLE "monokai" Pygments' style ID. Choose one from poetry run pygmentize -L styles.
COPYRIGHT Additional copyright statement to add in the third column of the footer.
DISCLAIMER Overide the disclaimer notice that gets displayed at the fourth column of the footer.
DISQUS_SITENAME Pelican can handle Disqus comments. Specify the Disqus sitename identifier here.
FAVICON_LINKS True Fetch link's icons from Google's favicons webservice.
GOOGLE_ANALYTICS Set to UA-XXXXXX-Y Property's tracking ID to activate Google Analytics.
LEFT_SIDEBAR HTML content to put as-is in the left sidebar.
LINKS_WIDGET_NAME "Links" Allows override of the name of the links widget.
LINKS A list of tuples (Title, URL) for links to appear in the second column of the footer.
MANUAL_LINKS When enabling this, you must pass the links (in LINKS & SOCIAL settins) not as tuples anymore, but as list, where every entry is formatted as you like
MENUITEMS A list of tuples (Title, URL) for additional menu items to appear at the beginning of the main menu.
RIGHT_SIDEBAR HTML content to put as-is in the right sidebar.
SITESUBTITLE A subtitle to appear in the header.
SITE_THUMBNAIL_TEXT Text displayed behind site's thumbnail.
SITE_THUMBNAIL Site's thumbnail URL as displayed in the header. Should be a square image of at least 80x80 pixels.
SOCIAL_WIDGET_NAME "Social" Allows override of the name of the “social” widget.
SOCIAL A list of tuples (Title, URL) to appear in the first columns of the footer.
TIPUE_SEARCH False Activate Tipue Search (javascript static search engine) into the site. Requires the tipue_search plugin.

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:

Feature CodeHilite Highlight
Clean copy and paste
Line numbering
Right justified numbers
Line start offset
Multiple line highlight
Nth line highlight
Filename
Long line wraps
Long line overflow (scrollbar)
Sticky left gutter
Line anchors WIP @ Pygments

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:

Plumage Python Markdown CodeHilite rendering

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:

Plumage PyMdown Extensions' Highlight rendering

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

About

🎨 Theme for Pelican, the static site generator.

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • CSS 63.7%
  • HTML 15.7%
  • JavaScript 14.0%
  • Python 4.6%
  • SCSS 2.0%