Getting Started with Pelican
There are a few things you'll need to get started with Pelican:
pelicanconf.py- pelican configuration file
content/- directory containing materials to render into a static site
- (optional) theme - either a local directory containing a theme, or a system-wide pelican theme
Use the magic-flying-pelican repository as a seed repo for getting started with Pelican.
Basically, copy the contents of the
into your own repository, and modify the contents for
your own static site.
We'll walk through what the
pelican/ directory contains and what you
need to change to get a simple static site up and running.
How Pelican Works
Let's cover the 101 of how Pelican works.
Pelican takes a pile of HTML, markdown, and other files, and compiles them into a static site. (The advantage of using a static site instead of a dynamic server like Flask or a dynamic language like PHP is speed.)
To do that, it reads configuration settings from
pelicanconf.py, which tell Pelican where to look
for the raw files, as well as other settings like
the theme to use.
The default location of content is the
directory, but more can be added.
The default behavior for Pelican is to serve a blog with a few static pages, but users can define themes that are static pages only (no blog component).
The themes work by providing a set of static files and a set of HTML Jinja templates. Pelican uses the static content and the theme to render the final page.
See pelican-themes repository for themes.
See live gallery of pelican themes.
Repository and Branch Layout
When using Pelican to create a static site on Github Pages, you will need to organize your repository and set up branches as follows.
Recommended way: project page
If you are hosting a project Github Pages site (that is, a Github Pages page for any arbitrary Github project), you should organize your repo as follows:
gh-pagesbranch contains all static content
masterbranch contains the pelican site
Uncommon way: personal page
If you are hosting a personal Github Pages site
(a repository under the account
yourusername.github.io), this should be
organized as follows:
masterbranch contains all static content
sourcebranch contains the
Clean way: pelican as a separate branch
If you have a large project or you really don't want to clutter your repository branch with Pelican files, you can also set up a three-branch model as follows:
masterbranch contains the source code for your project (no Pelican files)
sourcebranch contains the Pelican files for your site
gh-pagescontains all static content for the Github Pages page
While Pelican is flexible enough to handle many
directory layouts, let's cover a common pattern:
putting markdown files into
my-cool-project/ pelican/ pelicanconf.py output/ index.html ... content/ posts/ blog-post-1.md blog-post-2.md blog-post-3.md pages/ faq.md about.md contact.md img/ my-image-1.jpg my-image-2.jpg my-image-3.jpg
The pelican directory contains a configuration
pelicanconf.py, a folder with content
content/, and an output directory
where the final static files for the site go.
output/ directory will not be present
until you generate site content (see generating).
output/ directory should be ignored by git.
In a later section of this document we will cover
a pattern for linking output to a Github Pages
site (see workflow: update).