Pelican
From charlesreid1
Contents
Starting with Pelican
Begin by using pip to install pelican and markdown:
pip install pelican markdown
or install via Pelican Github repo:
Pelican documentation is here:
and the Pelican quickstart guide is here:
Using Pelican with Github Project Page
If you want to use pelican to manage a github project page, start by creating a "source code" bundle for your Pelican site in the master branch. This will deploy static content to the gh-pages branch, which is what shows up when you visit http://username.githubpages.io/project-name.
Starting Your Pelican Site
Start in the master branch of your project. Here, I'll use my Words, Words, Words project as an example.
$ pwd /Users/charles/codes/wordswordswords/pelican
Now I create the site with the pelican-quickstart command, answering some questions from Pelican:
$ pelican-quickstart Welcome to pelican-quickstart v3.5.0. 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? Words, Words, Words > Who will be the author of this web site? CR > 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) y > How many articles per page do you want? [10] > 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 /Users/charles/codes/wordswordswords/pelican
Creating Markdown Content for Pelican Site
Once your Pelican site has been created, we can create markdown content by putting markdown files into the content/ directory. For example,
Title: An Article Date: 2014-12-21 10:20 Category: Essay This is just an ordinary article.
We can then generate static content from the markdown files by running the pelican content command:
$ pelican content Done: Processed 1 article(s), 0 draft(s) and 0 page(s) in 0.33 seconds.
and preview the site by going into the output/ directory and running a simple HTTP server with Python:
$ cd output/ $ python -m SimpleHTTPServer Serving HTTP on 0.0.0.0 port 8000 ...
Then you can visit http://localhost:8000 to see the site preview locally.
The next steps involve connecting this output folder to the Github branch that is pointed to by our Github Project page's live hosted static content. That way, we can type pelican content to generate content, and then use git push to push the freshly-generated content to the live Github Pages project site.
Connecting Pelican Output to gh-pages Branch
The next step will allow you to deploy content directly to the live gh-pages branch, using Pelican.
In the project/pelican directory (in my case, wordswordswords/pelican):
$ ls Makefile cache content develop_server.sh fabfile.py output pelicanconf.py pelicanconf.pyc publishconf.py
We will first remove the output/ directory. Then we will check out a copy of the gh-pages branch to the output/ directory. Now, when we type pelican content, it will generate the static content directly in the gh-pages branch!
$ rm -rf output/ $ git clone -b gh-pages https://github.com/charlesreid1/wordswordswords.git output/ Cloning into 'output'... remote: Counting objects: 40, done. remote: Compressing objects: 100% (34/34), done. remote: Total 40 (delta 13), reused 29 (delta 3) Unpacking objects: 100% (40/40), done. Checking connectivity... done $ pelican content Done: Processed 1 article(s), 0 draft(s) and 0 page(s) in 0.31 seconds. $ ls output/ archives.html author authors.html categories.html category i-am-a-dummy.html index.html tags.html theme
Pelican Themes
You can create your own themes with Pelican, and this is where Pelican becomes a tool for organizing static web content that is a lot like Ruby's Jekyll.
Pelican Plugins
Workflow for Plugin Hacking
If you're having trouble while hacking on a Pelican plugin - if your site just doesn't seem to be updating, even after you change the code for a plugin - try deleting the cache/ directory. It will force Pelican to re-make ALL HTML pages, not just the ones it thinks have been updated.
You can also drop some debug statements into your plugin to see what's going on: put a import pdb; pdb.set_trace() statement into your plugin code.
Static, Non-Blog Sites with Pelican
If you want to make a static, non-blog page with Pelican, it is pretty straightforward to do.
I customized my theme's page.html so that I can implement arbitrary variables in my Markdown headers, and use those variables in conditional statements in page.html. This allows for greater flexibility and variety in the page styles I can use.
You can also customize the landing page by adding the save_as directive to the top of your Markdown file. If you specify the save_as page as index.html, it will override whatever index.html would have otherwise been made, to give you your own custom landing page in Markdown.
Advanced Pelican Configurations
You can do quite a bit with the pelican configuration file. The Pelican/Advanced page contains more examples of configuration files.
Configuration
Here is a typical Pelican configuration file for one of my projects.
#!/usr/bin/env python
# -*- coding: utf-8 -*- #
from __future__ import unicode_literals
AUTHOR = u'charlesreid1'
SITENAME = u'Cyborg Pelican'
#SITEURL = '/cyborg-pelican'
PATH = 'content'
TIMEZONE = 'America/Los_Angeles'
DEFAULT_LANG = u'en'
# --------------8<---------------------
# This is stuff that I have customized
# Don't try to turn HTML files into pages
READERS = {'html': None}
PLUGIN_PATHS = ['/temp/pelican-plugins/']
PLUGINS = ['liquid_tags','liquid_tags.include_code','liquid_tags.include_html']
CODE_DIR = 'code'
BOOKS_DIR = 'books'
STATIC_PATHS = ['images','code','books']
THEME = 'cmr-pelican-theme'
DISPLAY_PAGES_ON_MENU = False
# dark and pastels.
#BOOTSWATCH_THEME = 'darkly'
# dark blue and white
BOOTSWATCH_THEME = 'flatly'
# --------------8<---------------------
# Feed generation is usually not desired when developing
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
DEFAULT_PAGINATION = False
# Uncomment following line if you want document-relative URLs when developing
#RELATIVE_URLS = True