Pelican - Static Website/Blog Generator
Giles Orr
TPL
About this Slide Show
- As you've probably already discovered, clicking anywhere will advance the slides
- put the pointer in the lower right corner to find the controls (allows navigation and print view - the slashed zero)
- I've added extra notes to some slides in the print view - originally my speaking notes, they may be helpful to you if you're interested
- This is an S5 Slide Show: simple, easy to edit, and easy to post on any static web server, I highly recommend it
- S5 is by Eric Meyer, one of the original gods of CSS ...
Why Pelican
- common to all static site generators, hosting is very easy to arrange
- incredibly easy to maintain once set up
- if you can edit HTML, why use this?: Automated organization (should appeal to librarians)
- built-in code syntax highlighting for MANY languages
- something I use fairly heavily: built-in code syntax highlighting for MANY languages through Pygments (it's a Python thing)
- it's great for non-technical blogs and sites as well
- static sites can go on any web server at all
- Daniel (who started me using Pelican) recommends GitHub Pages, which are free and conveniently come with revision control ...
- "Automated organization" means "you provide the subject headings, we provide cross-linking and index pages"
Installation
- you need Python (2 or 3, but ... use 3)
- 'pip install pelican' OR 'dnf install python<N>-pelican' OR 'apt-get install pelican' use virtualenv if you know what you're doing
- 'pelican-quickstart' in the folder where you want it to live
- quickstart may be quick, but it's not obvious ...
- the documentation is at http://docs.getpelican.com/ - read that a bit first
- Python 2 is quite old: since Pelican supports Python 3, it would be more forward-looking to use it
- Mac users use pip, pelican doesn't seem to be in Homebrew
Quickstart
% pelican-quickstart
Welcome to pelican-quickstart v3.7.1.
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? code4lib
> Who will be the author of this web site? Giles
> 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) n
> Do you want to enable article pagination? (Y/n)
> How many articles per page do you want? [10] 20
> What is your time zone? [Europe/Paris] America/Toronto
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n)
> Do you want to upload your website using FTP? (y/N)
> Do you want to upload your website using SSH? (y/N)
> Do you want to upload your website using Dropbox? (y/N)
> Do you want to upload your website using S3? (y/N)
> Do you want to upload your website using Rackspace Cloud Files? (y/N)
> Do you want to upload your website using GitHub Pages? (y/N)
Done. Your new project is available at /home/giles/blog
- Know your timezone! If you're at this presentation, 'America/Toronto' is probably correct
- When unsure (most of the time) I went with the defaults
Your First Page(s)
- change into the content/ folder
- edit MarkDown/HTML or RST (ReStructuredText - it's a Python thing) pages
- consult the docs for a file template: http://docs.getpelican.com/en/3.6.3/content.html
- go up one folder (to the original blog folder) and run 'make html'
- the subfolder 'output/' now includes everything you need for your site
- 'make html' is very fast when you start. When you have hundreds of files, it will take longer. There are ways to regenerate only parts of the site ... but worry about that when you need it
RST Template Page
:title: Your Title Here
:date: 2017-04-27 11:20
:modified: 2017-04-27 16:43
:tags: comma, separated, list
:category: Blogging
:slug: generated-file-title
:author: Giles Orr
:status: draft
:summary: short summary of page contents
.. This is a comment. Remove the 'draft'
.. tag when you're ready to publish.
.. My template doesn't include the ':category:'
.. header as I don't use it.
- Not all headers are required, but until you know which you want it's safe to use all of the ones shown here.
- I use the Vim editor, and I've set it up so that any new file with the '.rst' extension is automatically templated as above. Vim will also set the correct ':date:' header when I first create the file, and every time I write the file it updates the ':modified:' header. You can see part of this detailed in my blog entry Vim: Updating a "Last Modified" Tag.
Configuration
- you'll probably want to change both the appearance and behaviour of Pelican
- have a good look at the structure of the generated site: it'll help to know it when you start modifying
- your first file is pelicanconf.py in the main folder
- after that I found I needed to install a theme so I could hack it
- modifying themes requires a knowledge of HTML, CSS, and Python (and maybe Jinja2) as they use all three (four) to generate your final output
- it's a big and somewhat complex templating system
- Jinja2 is a Python templating language, heavily used in Ansible (and probably elsewhere, but that's where I became familiar with it)
My Blog
- https://www.gilesorr.com/blog/
- I disabled Categories as they didn't interest me
- I use tags extensively (it's the librarian in me)
- I turned on the RSS feed for a friend who uses it
- I added a couple links to the header
- and - as with all my site ... I try for function, readability, and navigability over form because I'm not great at form and I don't much care
- "Categories" are very broad: a page can only be in one category. Tags are (to my mind) more useful: a page can have multiple tags.
Examples
- The pelicanconf.py file is your first point of entry to configuring a Pelican installation: technically, it's a Python file, but it's mostly of the form 'variable = value' and is easy to understand and edit