Pelican For Fast Site/Project Development

Overview

I've written a lot of detail on every step but it is actually very easy to use Pelican for non-blog web sites. Here's how it works:

1. Create a virtualenv and install Pelican and webassets Python packages (I use the same venv for all my Pelican projects).
2. Checkout pelican-plugins.
3. Edit the Pelican theme's base.html Jinja template to include the CSS and JavaScript files you need.
4. Create your pages' body content in files in content/pages in HTML, Markdown or reStructuredText.
5. Run make devserver and refresh your browser to see your changes or use this LiveReload script to automatically reload your browser. Repeat steps 3 and 4 until you are done.
6. Deploy to GitHub Pages: make github. Or deploy to your own server.

Setup the Environment

Install and configure Pelican for creating non-blog web sites:

1. Create a virtualenv and install pelican, webassets, cssmin, and jsmin (or any other CSS/JS filters supported by webassets):

   virtualenv ~/virtualenvs/pelican
   source ~/virtualenvs/pelican/bin/activate
   pip install pelican webassets cssmin jsmin
   

2. Check out the pelican plugins repository outside of your project (plugins are only used during the build process):

   git checkout https://github.com/getpelican/pelican-plugins.git
   

3. Create your project directory, run pelican-quickstart and answer the questions just like for a blog site:

   mkdir myproject && cd $_
   pelican-quickstart
   
   Welcome to pelican-quickstart v3.6.3.
   
   This script will help you create a new Pelican-based website.
   
   Please answer the following questions so this script can generate the files
   needed by Pelican.
   
   > Where do you want to create your new web site? [.]
   > What will be the title of this web site? Dog Agility Jump Height Calculator
   > Who will be the author of this web site? Steve Schwarz
   > What will be the default language of this web site? [en]
   > Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) y
   > /agility-jump-heights           <-- enter the name of your GitHub repository
   > Do you want to enable article pagination? (Y/n) n
   > What is your time zone? [Europe/Paris] America/Chicago
   > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) y
   > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) y
   > Do you want to upload your website using FTP? (y/N) n
   > Do you want to upload your website using SSH? (y/N) n
   > Do you want to upload your website using Dropbox? (y/N) n
   > Do you want to upload your website using S3? (y/N) n
   > Do you want to upload your website using Rackspace Cloud Files? (y/N) n
   > Do you want to upload your website using GitHub Pages? (y/N) y
   > Is this your personal page (username.github.io)? (y/N) n
   Done. Your new project is available at /home/dev/agility-jump-heights
   

4. Paste the following at the end of your pelican.conf:

   STATIC_PATHS = ['images']  # put page specific assets here
   PLUGIN_PATHS = ['../pelican-plugins']  # set this to the location of your plugins checkout
   PLUGINS = ['assets']
   THEME = './theme'          # All CSS/JS files go in directories under here
   # I only want to generate Pages so I disable all "blog-like" pages see Note in:
   # http://docs.getpelican.com/en/stable/settings.html?highlight=url_for#url-settings
   TAGS_SAVE_AS = ''          # Don't generate Tags pages
   TAG_SAVE_AS = ''
   CATEGORY_SAVE_AS = ''      # Don't generate Category pages
   AUTHOR_SAVE_AS = ''        # Don't generate Author pages
   DIRECT_TEMPLATES = ['index']  # Don't generate tag, category, or author output for some themes
   # In the generated output directory move files to the root and adjust their URLs to match:
   PAGE_URL = '{slug}.html'
   PAGE_SAVE_AS = '{slug}.html'
   INDEX_SAVE_AS = "/ignore/index.html"  # don't create normal index.html which lists all articles and pages
   

5. Copy any theme from pelican-themes into .theme or I just copy the notmyidea theme installed with Pelican from the virtualenv:

   cp -pR $VIRTUAL_ENV/lib/python*/site-packages/pelican/themes/notmyidea/ theme
   

6. Have Git ignore the output directory:

   echo "/output" >> .gitignore
   

Create Your Project Web Site

 {% assets filters="cssmin", output="css/style.%(version)s.min.css", "css/normalize.css", "css/skeleton.css", "css/style.css" %}
<link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}">
 {% endassets %}

{% assets filters="jsmin", output="js/main.%(version)s.min.js", "js/main.js" %}
<script src="{{ SITEURL }}/{{ ASSET_URL }}"></script>
{% endassets %}

{% extends "base.html" %}
{% block title %}{{ page.title }}{% endblock %}

{% block content %}
<div class="container">
{{ page.content }}
</div>
{% endblock %}

mkdir content/pages

<html>
    <head>
        <!-- By default used to create the URL slug -->
        <title>Dog Agility Jump Height Calculator</title>
        <!-- Override the default URL made up of the slug; needed for the index.html -->
        <meta name="save_as" content="index.html"/>
        <!-- any other metadata attributes as meta tags; none normally needed -->
    </head>
    <body>
        <!-- all  markup goes here. e.g. -->
        <h1>Hello World!</h1>
    </body>
</html>

make devserver

make github