How To Set This Page

About Pelican

Pelican is a utility that lets you create beautiful weblogs using just text files. Github Pages allows users to store page content in a git repository along with their code. By combining Pelican with Github Pages, you can have a reliable and attractive blog site for your projects.


1. Create a repository on GitHub

Head over to GitHub and create a new repository named, where username is your username (or organization name) on GitHub. Note that this repository should be public.


2. Clone the repository

Go to the folder where you want to store your project, and clone the new repository:

$ git clone
$ cd

3. Create new branch

When you enter, what will happen? And how can GitHub detect your html file in repository? In fact, GitHub automatically detects index.html file from the main branch, and presents this file as your website entrance. Therefore, we need place our page files (the output/ folder in pelican) in main branch. I strongly prefer not to keep all the Pelican configuration files and raw Markdown files in main branch. So I keep the Pelican configuration and the raw content in a separate branch I like to call notebook_source.

$ git checkout -b notebook_source
Switched to a new branch 'notebook_source'

4. Configure Pelican

Now it's time for content configuration. Pelican provides a great initialization tool called pelican-quickstart that will ask you a series of questions about your blog.

$ pelican-quickstart

You can take the defaults on every question except:

  • Website title (which should be unique and special)
  • Website author (which can be a personal username or your full name)
  • Time zone (Such as Asia/Shanghai)
  • Upload to GitHub Pages, which is a "y" in our case

5. Add pelican files to the notebook_source branch

Add all the Pelican-generated files to the content branch of the local Git repo, commit the changes, and push the local changes to the remote repo hosted on GitHub by entering:

$ git add .
$ git commit -m 'initial pelican commit to content'
$ git push origin content

6. Write content

Now you can get bloggy! All of your blog posts, photos, images, PDFs, etc., will live in the content directory, which is initially empty. We can use Markdown syntax. To begin creating a first post, enter:

$ cd content
$ touch

Next, open the empty file in your favorite text editor and add the following:

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds

This is the content of my super blog post.  

You can also have your own metadata keys (so long as they don’t conflict with reserved metadata keywords) for use in your templates. The following table contains a list of reserved metadata keywords:


7. Install ghp-import

$ pip install pelican ghp-import Markdown

8. Publish

All that's left to do is:

  • Run Pelican to generate the static HTML files in output. -r is to enable watching for your modifications, instead of manually re-running it every time you want to see your changes.
$ pelican content -s -r
  • Use ghp-import to add the contents of the output directory to the main branch:
$ ghp-import -m "Generate Pelican site" --no-jekyll -b main output
  • Push the local main branch to the remote repo:
$ git push origin main
  • Commit and push the new content to the content branch:
$ git add content
$ git commit -m 'added a first post, a photo and an about page'
$ git push origin content

9. Finally!

Now the exciting part is here when you get to view what you've published for everyone to see! Open your browser and enter:

[Note]: I use the theme buruma.

How to modify in the future

After modification, under the notebook_source category and notebook_source branch, enter:

pelican content

to generate output/ files.


git add -u 
git commit -m "."
git push origin notebook_source:notebook_source

to commit notebook_source branch. (-u only add changes of tracked files)


ghp-import -m "Generate Pelican site" --no-jekyll -b main output -c

to put new output content to main branch.

lastly, enter:

git push origin main:main

to commit main branch.

Check the deployments of Page

Note, Github also has a deployment page. after push all modification, you can enter:

where lists the deployments and the time they were deployed.


  1. Another useful blog:
  2. Pelican document
  3. Pelican themes
  4. Buruma Theme