Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1206 lines (890 sloc) 47.9 KB

Eevee -- A Material Design theme for Pelican

slug:eevee

Eevee, the Pokémon

Introduction

Eevee is a theme for Pelican, based on Google's Material Design specification. It is named after the Pokémon Eevee because -- like the Pokémon -- it can evolve in to many 'elemental types.'

Features

Plugins supported out-of-the-box

Eevee ships with all the HTML, CSS and JavaScript required for the following plugins but does not need any of them to function correctly. If a plugin is supported but not used, the HTML, CSS and JavaScript simply won't be included.

Typography

Eevee Typography

Google's Roboto font is used for typography, Material Icons and Font Awesome are included too.

Screenshots

.. gallery:: content/images/eevee_page/
    :columns: 3

Installation

Download the latest Eevee release from GitHub and extract it in to your Pelican website directory and rename the directory to eevee.

Install the theme using pelican-themes.

pelican-themes -i eevee

All you need to do after that is set the THEME variable to eevee in your pelicanconf.py.

THEME = 'eevee'

Customising Eevee

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

.. lightbox::
    :thumb: /images/eevee-menu.png
    :large: /images/eevee-menu.png
    :alt: Header menu
    :caption: Header menu
    :align: center

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

MENUITEMS = (('Contact', '/contact/'), ('Software', '/software/'),
             ('Donate', '/donate/'),
             ('.onion', 'http://omgkuraio276g5wo.onion/'))

Using DISPLAY_PAGES_ON_MENU will automatically add pages to the menu.

DISPLAY_PAGES_ON_MENU = True

Footer

.. lightbox::
    :thumb: /images/eevee-footer-menu-thumb.png
    :large: /images/eevee-footer-menu.png
    :alt: Footer menu
    :caption: Footer menu
    :align: center

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/'), ('Software', '/software/'),
             ('Donate', '/donate/'),
             ('.onion', 'http://omgkuraio276g5wo.onion/'))

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 = (('blackhole.io', 'https://blackhole.io'), )

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

.. lightbox::
    :thumb: /images/eevee-copyright-disclaimer-thumb.png
    :large: /images/eevee-copyright-disclaimer.png
    :alt: Copyright and disclaimer
    :caption: Copyright and disclaimer
    :align: center

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 &amp; rainbow sparkles.'
COPYRIGHT = '<a href="https://kura.io/eevee/" title="Eevee">Eevee</a> theme by <a href="https://kura.io/" title="kura.io">kura.io</a>'

Table of contents for articles and pages

.. lightbox::
    :thumb: /images/eevee-toc.png
    :large: /images/eevee-toc.png
    :alt: Table of contents
    :caption: Table of contents
    :align: center

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

.. lightbox::
    :thumb: /images/eevee-author-card.png
    :large: /images/eevee-author-card.png
    :alt: Author card
    :caption: Author card
    :align: center

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

Enabling the author card

Enabling the author card is as simple as setting an option in pelicanconf.py.

USE_AUTHOR_CARD = True

You can disable it by setting to False or removing the setting entirely.

USE_AUTHOR_CARD = False

Using your own avatar

A default avatar placeholder is provided with the theme, you can easily use your own avatar by setting an option in pelicanconf.py.

AUTHOR_CARD_AVATAR = '/images/kura.png'

The maximum size that you should use are 250x250 pixels.

Setting a description

Like all the other options above, setting a description for your author card requires a single config option.

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

You can add HTML and other various things to this description.

Social buttons

By default, the author card section will display links from your SOCIAL list.

This isn't always what you want though.

The SOCIAL list is used in other parts of the theme and the format may not look good added to your author card.

To make things more flexible, the author card section can have it's own social links.

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'), )

Some default styling rules are included with Eevee, they are as follow:

Site Link colour Hover colour
Twitter #039BE5 #0277BD
Facebook #1565C0 #0D47A1
Google+ #F44336 #D32F2F
GitHub #212121 #616161
Instagram #8BC34A #689F38

You can add your own new styles or overwrite an existing style using the href selector.

For example, adding a selector style for https://kura.io would be done like the example below.

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

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

Dynamically disabling author card on an article or page

As of Eevee version 0.0.12, it is now possible to disable the author card feature on a per-article or per-page basis using metadata.

Using reStructuredText:

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

Using Markdown:

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

DISQUS_SITENAME = 'somethinghere'

Setting this option will enable Disqus for articles.

Muut

MUUT_SITENAME = 'somethinghere'

Setting this option will enable Muut for articles.

Comments on pages

You can display comments on pages as well as articles with the following option. By default this is disabled.

COMMENTS_ON_PAGES = True

Dynamically disabling comments on an article or page

As of Eevee version 0.0.12, it is now possible to disable comments on a per-article or per-page basis using metadata.

Using reStructuredText:

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

Example content

Using Markdown:

Title: Example title
Slug: example
Comments: False

Example content

Sharing options

.. lightbox::
    :thumb: /images/eevee-share-buttons.png
    :large: /images/eevee-share-buttons.png
    :alt: Share buttons
    :caption: Share buttons
    :align: center

Share buttons

By default four share buttons are configured;

  • Twitter,
  • Facebook,
  • Google+,
  • and Email.

These buttons will appear on all articles and pages.

If you have comments enabled either using Disqus or Muut, on articles a fifth button will be shown which shows the user comments for the current article.

Options

USE_OPEN_GRAPH = True

If set, Open Graph meta tags will be added.

USE_TWITTER_CARDS = True

If set, Twitter meta tags will be added.

TWITTER_USERNAME = 'kuramanga'

Used in conjunction with USE_TWITTER_CARDS, adds the "via" meta tag.

Adding an image to Open Graph and Twitter meta tags

There are two ways of adding an image to Twitter and Open Graph so that when someone shares your content, an image will be added too.

You can add og_image to the file metadata of an article or page, allowing you to configure and image to use per item.

Using reStructuredText:

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

Example content

Using Markdown:

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

Example content

Or you can set OPEN_GRAPH_IMAGE to an image location in the pelicanconf.py settings file and adding the relevant directory to the STATIC_PATHS and EXTRA_PATH_METADATA settings.

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

Archives

.. lightbox::
    :thumb: /images/eevee-menu.png
    :large: /images/eevee-menu.png
    :alt: Header menu
    :caption: Header menu
    :align: center

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

GOOGLE_ANALYTICS = 'abc1234'

Piwik

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

Open Web Analytics

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

GoSquared

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

.. lightbox::
    :thumb: /images/eevee-menu.png
    :large: /images/eevee-menu.png
    :alt: Feed menu item
    :caption: Feed menu item
    :align: center

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

.. lightbox::
    :thumb: /images/eevee-search-menu-item.png
    :large: /images/eevee-search-menu-item.png
    :alt: Search menu item
    :caption: Search menu item
    :align: center

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

.. lightbox::
    :thumb: /images/eevee-headerid.png
    :large: /images/eevee-headerid.png
    :alt: Header permalink
    :caption: Header permalink
    :align: center

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

.. lightbox::
    :thumb: /images/eevee-related.png
    :large: /images/eevee-related.png
    :alt: Related articles
    :caption: Related articles
    :align: center

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

.. lightbox::
    :thumb: /images/eevee-series.png
    :large: /images/eevee-series.png
    :alt: Articles in a series
    :caption: Articles in a series
    :align: center

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">

All configuration settings

Setting name Default Description
SITENAME   The title of your website
AUTHOR   Your name
THEME_PRIMARY blue_grey

Primary colour scheme

Primary and accent colours

THEME_ACCENT pink

Accent colour scheme

Primary and accent colours

MEGA_FOOTER True

Display the mega footer

Header and footer options

DISCLAIMER  

Disclaimer displayed on the footer

Primary and accent colours

COPYRIGHT  

Copyright notice displayed on the footer

Primary and accent colours

USE_AUTHOR_CARD False

Display about author card on articles

Author card

AUTHOR_CARD_ON_PAGES False

Display about author card on pages

Author card

AUTHOR_CARD_AVATAR /theme/images/default_avatar.png

Avatar to display on the author card

Author card

AUTHOR_CARD_DESCRIPTION  

Description to display on the author card

Author card

AUTHOR_CARD_SOCIAL SOCIAL

Social media links to display on the author card

Author card

MENUITEMS []

Displayed on header and mega footer

Header and footer options

LINKS []

Blogroll to display on the mega footer

Header and footer options

SOCIAL []

Social links to display on the menu and mega footer

Header and footer options

DISPLAY_PAGES_ON_MENU False

Display pages on the menu and mega footer

Header and footer options

DISPLAY_CATEGORIES_ON_MENU False

Display categories on the menu and mega footer

Header and footer options

COMMENTS_ON_PAGES False

Add Diqus or Muut comments on pages

Disqus or Muut for comments

MUUT_SITENAME  

Muut unique identifier for the website

Disqus or Muut for comments

DISQUS_SITENAME  

Disqus unique identifier for the website

Disqus or Muut for comments

USE_OPEN_GRAPH False

Add Open Graph meta tags

Sharing options

USE_TWITTER_CARDS False

Add Twitter meta tags

Sharing options

TWITTER_USERNAME  

Add your Twitter username to mega tags

Sharing options

OPEN_GRAPH_IMAGE  

Add an image to Twitter and Open Graph

Sharing options

OWA_SITE_ID  

OWA unique identifier for the website

Google Analytics, Piwik, Open Web Analytics and GoSquared

OWA_URL  

URL to the OWA installation

Google Analytics, Piwik, Open Web Analytics and GoSquared

PIWIK_SITE_ID  

Piwik unique identifier for the website

Google Analytics, Piwik, Open Web Analytics and GoSquared

PIWIK_URL  

URL to the Piwik installation

Google Analytics, Piwik, Open Web Analytics and GoSquared

PIWIK_SSL_URL PIWIK_URL

Secure URL to the Piwik installation

Google Analytics, Piwik, Open Web Analytics and GoSquared

GOOGLE_ANALYTICS  

Google Analytics unique identifier for the website

Google Analytics, Piwik, Open Web Analytics and GoSquared

ARCHIVES_URL  

URL for archives and add a menu item for it

Archives

ARCHIVES_SAVE_AS  

Location to save archives

Archives

MONTH_ARCHIVE_SAVE_AS  

Location to save monthly archives

Archives

YEAR_ARCHIVE_SAVE_AS  

Location to save yearly archives

Archives

FEED_RSS  

Enable the RSS feed and add a menu item for it

Feeds

FEED_ATOM  

Enable the Atom feed and add a menu item for it

Feeds

Additional tweaks and modifications

Additional things you can tweak and modify are available on kura.io.

Changelog

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

License

Eevee is released under the MIT license which is also outlined below.

(The MIT License)

Copyright (c) 2016 Kura

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the 'Software'), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
You can’t perform that action at this time.