Quickguide to start a static website with Pelican

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

  1. It's open sourced at github/pelican, with many plugins and themes.
  2. 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.


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

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.


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

To deploy a theme:

  1. git clone the theme folder
  2. 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:

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


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
FAVICON = '/images/favicon.ico'  # see note

# dead link options
    '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'

DELETE_OUTPUT_DIRECTORY = True  # delete develop cache if set in True

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


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.


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:

  1. git clone the plugin folder
  2. In pelicanconf.py, define PLUGIN_PATHS and PLUGINs as explained in Setups.
  3. 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
Published: Sat 01 September 2018. By Dongming Jin in

Comments !