Using Pelican blog on Github pages

Posted on September 23, 2017 in DevOps
Updated: November 26, 2017

This blog is part of a serie

  1. Using Pelican blog on Github pages (this blog)
  2. Using Pelican Themes
  3. Setting Pelican blogs in "draft"

I had some reasons for moving a blog from Wordpress to GitHubPages. You can read about reason, pro and cons here

In this blog I setup a Pelican blog site from Windows and host it on GitHub Pages.


Installation - Prerequisites

Installation - Pelican

  • As admin:
    • pip install pelican markdown
  • Create a folder for the Pelican source
    • MD
    • CD
  • Create a pelican site following
  • pelican-quickstart
    • Do you want to specify URL prefix? Answer
    • Do you want to upload using xxx? Answer N untill the xxx = GitHub Pages

Create some content

  • Create a blog e.g ~/content/yourcategoryno1/
  • Preview content
  • On Windows - in root create a file called serve.bat with the content:
pelican content
cd output
start "" "http://localhost:8000/"
python -m pelican.server
REM Ctrl-C to quit
  • ... then you can pre-view your content with .\serve
  • Images
    • In add line STATIC_PATHS = ['img', 'pdf']
    • Create an image e.g ~/content/img/hello.png
    • Link to the file with ![picture alt](img/hello.png "Mickey Mouse")
  • Links
    • External: [link desc]({:target="_blank"}
    • Internal: [link desc]({filename}/yourcategoryno1/{:target="_blank"}
  • Optionally edit more settings in - see
  • add a favicon.ico to root

Prepare GIT as VersionControlSystem

  • Fetch .gitignorefrom - save it to root
  • Create a ~/ - just for the source branch
  • Install publish tool
    • pip install ghp-import
  • Create local git repo
    • git init
  • Create a remote repo via for your github page build in GitHub. Call it
  • Connect to repo and print remote repo
    • git remote add origin
    • git remote -v
  • Create new branch for the pelican source
    • git checkout -b pelican

Deploy you blog

  • (Foreach) Commit source
    • git add .
    • git commit -a -m "Initial commit"
    • git push -u origin pelican
  • (Foreach) Publish build to master then publish
    • pelican content -o output -s
    • ghp-import output -r origin -b master
    • git push origin master
    • git checkout pelican
  • On Windows - in root create a file called publish.bat with the content:
git add .
git commit -a -m %1
git push -u origin pelican
pelican content -o output -s
ghp-import output -r origin -b master
git push origin master
git checkout pelican
  • ... then you can publish by .\publish "some comment"


I'm using Visual Studio Code, that has a nice Markdown preview - probably a plugin. But you could use NotePad for that matter.

picture alt

Day to day Workflow

  1. Open VS Code
  2. Open VS Code terminal 1 - T1
    • .\serve #code
    • A browser opens and navigates to http://localhost:8000
  3. Add a new .md file in \content\ and add some content
  4. Open VS Code terminal 2 - T2
    • .\build #code
    • F5 - refresh browser to see the new content
    • .\publish "file published" #code
  5. Browse to

Tip: If I don't want to publish a file I rename it to .txt - then it won't be published before I rename it back to .md.
It will still end up on your host - GitHubPages, so don't keep secrests in there.
If you want it published for review without being included in any content lists, then you can publish the document as draft with Status: draft.
Then the document will be put in the /drafts/ folder.

Continue in Using Pelican Themes


GitHub pages




The End