Eevee — A Material Design theme for Pelican

Primary and accent colours

The primary and accent colours are configured using the THEME_PRIMARY and THEME_ACCENT options respectively.

You can find available primary and accent colours on Material Design Lite. This website also shows you accents that won’t work well with the primary colour you choose.

THEME_PRIMARY = "blue"

THEME_ACCENT = "amber"

By default the colour scheme is blue grey for the primary and pink for the accent.

THEME_PRIMARY = "blue_grey"
THEME_ACCENT = "pink"

Custom CSS

Inside the Eevee static folder is a custom.css file. Anything added to this file will overwrite any of the core CSS. You can use this file to modify any part of the interface you wish, including changing the Pygments CSS.

This allows you to tinker with the design as much as you like without breaking the core theme.

Header and footer options

Header

Header menu (click to view large image)

To configure links in the header, use the MENUITEMS option.

MENUITEMS = [
    ("Contact", "/contact/"),
    ("Eevee", "/eevee/"),
    ("Software", "/software/"),
]

Using DISPLAY_PAGES_ON_MENU will automatically add pages to the menu.

DISPLAY_PAGES_ON_MENU = True

Footer

Footer menu (click to view large image)

You can display links in the footer, by default this option is enabled but can be turned off using the MEGA_FOOTER option. See the Screenshots section for an example of the mega footer.

MEGA_FOOTER = True  # default
MEGA_FOOTER = False  # disable the footer

Up to four columns can be displayed in the footer.

The first column displays the links from MENUITEMS.

MENUITEMS = [
    ("Contact", "/contact/"),
    ("Eevee", "/eevee/"),
    ("Software", "/software/"),
]

Using DISPLAY_PAGES_ON_MENU will automatically add pages to the menu.

DISPLAY_PAGES_ON_MENU = True

The second column displays categories, this is enabled using DISPLAY_CATEGORIES_ON_MENU.

DISPLAY_CATEGORIES_ON_MENU = True

The third column displays social links from SOCIAL.

SOCIAL = [
    ("Github", "https://github.com/kura"),
    ("Twitter", "https://twitter.com/kuramanga"),
]

And finally, the fourth column displays links from LINKS.

LINKS = [
    ("Eevee", "https://kura.gg/eevee/"),
    ("Blackhole", "https://kura.gg/blackhole/"),
]

The footer will scale based on options you configure, so if you set MENUITEMS and LINKS but not SOCIAL, there will be no gap.

Setting your own copyright notice and disclaimer

Copyright and disclaimer (click to view large image)

You can change the disclaimer and copyright notice displayed in the footer with the following variables.

DISCLAIMER = "Powered by love & rainbow sparkles."
COPYRIGHT = """Source code and content are released under the <a href="/license/">MIT license</a>."""

You can see either or both to False to disable these notices being displayed.

DISCLAIMER = False
COPYRIGHT = False

The default values for these are as below, although you are under no obligation to keep either of them.

DISCLAIMER = "Powered by love & rainbow sparkles."
COPYRIGHT = """<a href="https://kura.gg/eevee/" title="Eevee">Eevee</a> theme by <a href="https://kura.gg/" title="kura.gg">kura.gg</a>"""

Table of contents for articles and pages

Table of contents (click to view large image)

A table of contents section is added to an article or page if it exists as a variable called toc in the article or page object.

The extract_toc adds a toc option for RST and Markdown content.

The extract_toc plugin adds an ugly header element by default, I have a modified version on GitHub that returns nicer HTML.

Author card

Author card (click to view large image)

The author card is disabled by default, below are instructions on enabling it and customising it.

USE_AUTHOR_CARD = True

USE_AUTHOR_CARD = False

AUTHOR_CARD_AVATAR = "/images/kura.png"

AUTHOR_CARD_DESCRIPTION = "My name is Kura and I break things."

AUTHOR_CARD_SOCIAL = [
    ("""<i class="fa fa-github" aria-hidden="true"></i>""", "https://github.com/kura"),
    ("""<i class="fa fa-twitter" aria-hidden="true"></i>""", "https://twitter.com/kuramanga"),
]

nav.eevee-ac-author__social a[href^="https://kura.gg"] {
  color: #039BE5 !important;
}

nav.eevee-ac-author__social a[href^="https://kura.gg"]:hover {
  color: #0277BD !important;
}

Example title
#############
:slug: example
:author_card: False

Title: Example title
Slug: example
Author_card: False

Disqus or Muut for comments

You can only enable Disqus or Muut, not both. Disqus takes priority over Muut in terms of how the configuration variables are handled.

DISQUS_SITENAME = "somethinghere"

MUUT_SITENAME = "somethinghere"

COMMENTS_ON_PAGES = True

Example title
#############
:slug: example
:comments: False

Example content

Title: Example title
Slug: example
Comments: False

Example content

Sharing options

Share buttons (click to view large image)

USE_OPEN_GRAPH = True

USE_TWITTER_CARDS = True

TWITTER_USERNAME = "kuramanga"

Example title
#############
:slug: example
:og_image: /images/example.png

Example content

Title: Example title
Slug: example
Og_image: /images/example.png

Example content

OPEN_GRAPH_IMAGE = "/images/example.png"
STATIC_PATHS = [
    # ...
    "images",
    # ...
]
EXTRA_PATH_METADATA = {
    # ...
    "images": {"path": "images"},
    # ...
}

Archives

Header menu (click to view large image)

Eevee supports full archives and archives broken down by year and month.

To enable the full archive section, you need to enable the relevant setting in your pelicanconf.py file.

ARCHIVES_URL = "archives.html"
ARCHIVES_SAVE_AS = "archives.html"

Enabling the periodic archives for year and/or month is as simple as enabling their respective options in pelicanconf.py

YEAR_ARCHIVE_SAVE_AS = "{date:%Y}/index.html"
MONTH_ARCHIVE_SAVE_AS = "{date:%Y}/{date:%m}/index.html"

More information on archive settings can be found in the Pelican documentation.

Google Analytics, Piwik, Open Web Analytics and GoSquared

All four of these options can be enabled at the same time, should you wish to do so.

GOOGLE_ANALYTICS = "abc1234"

PIWIK_SITE_ID = "123456"
PIWIK_URL = "example.com"
# PIWIK_SSL_URL = ""  # Defaults to https://PIWIK_URL

OWA_SITE_ID = "123456"
OWA_URL = "https://example.com/owa/"

GOSQUARED_SITENAME = "123456"

Feeds

You can use the FEED_RSS and FEED_ATOM options to enable RSS and Atom feeds respectively.

FEED_RSS = "feeds/rss.xml"

FEED_ATOM = "feeds/atom.xml"

Feed menu item

Feed menu item (click to view large image)

Enabling either FEED_RSS or FEED_ATOM will automatically add a menu item for that feed. If MEGA_FOOTER is also enabled a link to the feed will be added there too.

Eevee prefers RSS over ATOM, if you enable both feed types a menu item will only be created for RSS, although both feeds will be added as alternate link tags.

Category and tag pages

To display all articles in specific categories or tags, you need to add the relevant settings.

An example for categories is below.

CATEGORY_URL = "category/{slug}/"
CATEGORY_SAVE_AS = "category/{slug}/index.html"
CATEGORIES_URL = "categories/"
CATEGORIES_SAVE_AS = "categories/index.html"
DIRECT_TEMPLATES = [
    # ...
    "categories",
    # ...
]

And below is an example for tags.

TAG_URL = "tag/{slug}/"
TAG_SAVE_AS = "tag/{slug}/index.html"
TAGS_URL = "tags/"
TAGS_SAVE_AS = "tags/index.html"
DIRECT_TEMPLATES = [
    # ...
    "tags",
    # ...
]

Plugin: Search functionality

Search menu item (click to view large image)

Eevee is configured to work with tipue_search out-of-the-box, all you need to do is enable the plugin and add the search template setting.

PLUGINS = [
    # ...
    "tipue_search",
    # ...
]

DIRECT_TEMPLATES = [
    # ...
    "search",
    # ...
]

Plugin: Permalinks in headlines

Header permalink (click to view large image)

reStructuredText does not add anchors to headings by default, adding reference links on headings means you can send the link to someone and have the browser automatically display the relevant section.

Eevee is configured out-of-the-box to support adding these references using the headerid plugin.

Plugin: Related articles

Related articles (click to view large image)

Related articles functionality is provided by the related_posts plugin.

Installing it will automatically enabled the functionality within Eevee.

PLUGINS = [
    # ...
    "related_posts",
    # ...
]

Plugin: Articles in a series

Articles in a series (click to view large image)

Series article functionality is provided by the series plugin.

Installing it will automatically enabled the functionality within Eevee.

PLUGINS = [
    # ...
    "series",
    # ...
]

Plugin: Minimise CSS and JavaScript

To minimise/compress all CSS or JavaScript, simply install the assets plugin.

Eevee is configured to automatically compress all CSS and JavaScript files it uses if the assets plugin is enabled, including files related to the search functionality.

PLUGINS = [
    # ...
    "assets",
    # ...
]

Advanced pagination

By default, Eevee will display pagination links on the index page of articles. Enabling the neighbors will automatically add a previous and next button to the article page, allowing pagination without going back to the index page.

The default Pelican pagination settings are not very pleasing, for more information on how to customise them to better and be more intuitive please look at the Pelican documentation.

DNS prefetch

DNS prefetching is enabled by default and managed automatically.

The following features will have respective DNS prefetch settings that will be applied if the feature is enabled;

• Disqus,
• Piwik,
• GoSquared,
• Google Analytics and,
• Open Web Analytics.

For example, the following would be applied if you had Disqus and Google Analytics enabled.

<link rel="dns-prefetch" href="EXAMPLE.COM">
<link rel="dns-prefetch" href="//code.getmdl.io">
<link rel="dns-prefetch" href="//disqus.com">
<link rel="dns-prefetch" href="//a.disquscdn.com">
<link rel="dns-prefetch" href="//EXAMPLE.disqus.com">
<link rel="dns-prefetch" href="//glitter-services.disqus.com">
<link rel="dns-prefetch" href="//google-analytics.com">
<link rel="dns-prefetch" href="//www.google-analytics.com">

0.0.14

Compare changes

• Remove references to kura.io

0.0.13

Compare changes

• Removed Google Plugs from share template.

0.0.12

Compare changes

• Updated share colours to be from the Material Design palette.

• Added some automatic colouring of links/icons for AUTHOR_CARD

• Added ability to disable comments and author_card for a specific page or article using metadata.

  Using reStructuredText:

  Example title
  #############
  :slug: example
  :author_card: False
  :comments: False
  

  Using Markdown:

  Title: Example title
  Slug: example
  Author_card: False
  Comments: False
  

0.0.11

Compare changes

• Stop using base64 fonts, dumb idea to begin with.
• Tidy up font sizes in headers.

0.0.10

Compare changes

• Bug fixes in template styles.

0.0.9

Compare changes

• Huge overhaul of theme… Too much to list, check out the documentation.

0.0.8

Compare changes

• Added better templates for tags and categories.

0.0.7

Compare changes

• Fixed RSS and Atom having the wrong types.

0.0.6

Compare changes

• Updated archive templates so they aren’t terrible.
• archive will automatically links to year and month archives if YEAR_ARCHIVE_SAVE_AS or MONTH_ARCHIVE_SAVE_AS are set.
• partial_archives template now works as expected instead of showing every article.
• Added archive to header and footer menus.

0.0.5

Compare changes

• Template clean up, mostly making the HTML itself look prettier to edit.
• Added aria labels to elements to improve accessibility.
• Added structures to articles and pages, using schema.org additional markup.

0.0.4

• Accidentally messed up Disqus and variable names where not used, so comments didn’t actually work properly…
• Load fonts from base64 in the CSS file.

0.0.3

• Add ability to use muut instead of Disqus using MUUT_SITENAME variable.
• Make the share buttons nicer.
• Added “back to top” links.

0.0.2

• Replace vh definitions with em for ribbon.
• Replace truetype fonts with woff2 and woff.

0.0.1

• Eevee released