Quickguide to start a static website with Pelican

There are many options to build a website. My reason to use Pelican is because

It's open sourced at github/pelican, with many plugins and themes.
I want to get my website up and running in one week.

If you are familiar with Python and markdown, the Quickstart provides enough instruction to get started. Here I'm putting together the commands and adding some extra plugins for making this website.

Note: Essentially, Pelican converts text files into HTML files, just like pandoc.

TOC

Get started
File structure
Themes
Setups
Developing
Write the first article
Add plugins
Useful tricks

Get started

# installation
pip install pelican markdown

# start a project
mkdir -p ~/projects/yoursite  # make sure there is no special character in the path to your project
cd ~/projects/yoursite
pelican-quickstart

For questions that have default values denoted in brackets, feel free to use the Return key to accept those default values. Don't worry too much. Most of the values are stored in pelicanconf.py and publishconf.py.

File structure

Here is an example of the file structure for a demo project.

.
├── Makefile  # use `make help` for manual, it is very self-descriptive 
├── content
│   ├── articles  # folder for blog articles
│   │   └── hello.md
│   ├── pdfs  # local pdfs to include in articles
│   │   └── file.pdf
│   ├── images  # local images to include in articles
│   │   └── picture.png
│   └── pages  # front pages like About Me, Research
│       ├── Research.md
│       └── About Me.md
├── develop_server.sh  # script to control a local pelican server, i.e. on a RPi
├── fabfile.py  # script to control a remote server by Fabric
├── output  # output of html files
│   ├── ...
│   └── ...
├── pelicanconf.py  # configure file based on answered values
└── publishconf.py  # configure only used in `make publish`

Note: Pelican doesn't recognize HTML files in content/pdfs folder at the moment. Any self-generated HTML files has to be manually copied to the output/pdfs folder.

Themes

Resources
- Themes gallery
- Github collections
- pelican blue: the one I used here.

Note: for many themes, the default index is defined as the list of blog articles.

To deploy a theme:

git clone the theme folder
In pelicanconf.py, add THEME = "path/to/theme"

Or use flag when build a project, pelican -t ~/pelican-themes/theme-name

The basic structure of a theme folder is:

.
├── static
│   ├── css
│   │   ├── pygments.css
│   │   └── style.css
│   ├── images
│   │   └── icons
│   └── js
│       └── comments.js
└── templates
    ├── archives.html
    └── ...

To customize or build a theme:

modify or create new css, js files and html templates.
pelican-themes -i {your_theme_name}

Setups

The complete setting list can be found at here. Many of which are not needed. Here I covered some setups for this website.

The pelicanconf.py file explained:

...
# some general setup
SITEURL = 'http://localhost:8000'  # use the url for test/local server
PATH = 'content'  # path to the folder of contents
STATIC_PATHS = ['images', 'pdfs']  # folders to be copied to output, i.e. `images/picture.png` can be accessed by `siteurl/images/picture.png` in any articles
TIMEZONE = 'America/Chicago'  # based on tz database
MENUITEMS = (('Blogs', SITEURL),)  # add index into site map formed by pages
THEME = "path/to/theme" 
PLUGIN_PATHS = ["path/to/plugin1","path/to/plugin2"]
PLUGINS = ['render_math','deadlinks', 'photos', 'representative_image']  # see `useful plugins` section

# optional setup
TWITTER_USERNAME = ''  # if using twitter related functions
LINKS = (('Pelican', 'http://getpelican.com/'),)  # external links
SIDEBAR_DIGEST = ''
FAVICON = '/images/favicon.ico'  # see note

# dead link options
DEADLINK_OPTS = {
    'archive':  True,
    'classes': ['custom-class1', 'disabled'],
    'labels':   True,
    'timeout_duration_ms': 1000,
    'timeout_is_error':    False,
}

Note: FAVICON is the icon for this website, mine is made of my initials using favicon-generator.

The publishconf.py file explained:

SITEURL = ''  # your web domain
MENUITEMS = (('Blogs', SITEURL),)  # add index into site map formed by pages
RELATIVE_URLS = False  # document-relative URLs, useful when developing

# feeds generation
FEED_ALL_ATOM = 'feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'
FEED_DOMAIN = SITEURL

DELETE_OUTPUT_DIRECTORY = True  # delete develop cache if set in True

DISQUS_SITENAME = ""  # see notes
GOOGLE_ANALYTICS = ""  # see notes

Note:

DISQUS: follow guide to use DISQUS for commenting. Static comment plugins exist to have full control of contents.
Google Analytics: Set to ‘UA-XXXX-YYYY’ from Google Analytics to help track traffic.

Developing

It is very straight-forward if you know how to read the Makefile.

Start the server: make devserver or ./develop_server.sh start
Stop the server: make stopserver or ./develop_server.sh stop
Publish the website: make publish
Upload website to web server
- FTP: make ftp_upload
- ssh: make ssh_upload
- using Fabric: python fabfile.py
- ...

Write the first article

Title: My First Article
Date: 2010-12-03 10:20
Category: Articles
Tags: tag1, tag2
Featured_image: /images/picture.png
Status: draft
Modified: 08/14/2018


Article Content In Markdown Format

Add plugins

A collection of plugins can be found here

Use of plugin:

git clone the plugin folder
In pelicanconf.py, define PLUGIN_PATHS and PLUGINs as explained in Setups.
Add additional setup following special instruction of the plugin.

Useful tricks

copyright footer: generate free privacy policy and style it to protect your website
render_math: support math in markdown
representative_image: extracts a representative image (i.e, featured image) from the article's summary or content.
pin_to_top: pin an article to top

Comments !