Creating A Pelican-Powered Site on GitHub Pages
I no longer host this site on GitHub Pages. However, the following article may still prove useful to you. Enjoy! (2014-06-02)
As stated in my "Hello World" post, kevinrichardson.co is created with Pelican — a static website generator — and hosted on GitHub Pages. Benefits of static websites are abundant. This combination allows one to easily update the look and feel of a website as well as its content while maintaining a complete revision history through the Git version control system. Static websites are awesome because they allow one to maintain a copy of her content and not worry about the "walled garden" effects of sites like Facebook wherein content can be challenging to export to other platforms. Generators are incredibly useful because they allow one to separate her content from her presentation templates. Because static websites are HTML and related assets, it is incredibly easy to move one's site to other webhosts as is necessary or desired. Another nicety exists in that GitHub Pages also provides the URI
http://username.github.com and optionally allows the user to use her own domain. Static website generators (like Pelican) generally allow one to write content in lightweight markup languages (like Markdown or reStructuredText) that is translated to HTML as necessary.
This post introduces how I maintain this website and (hopefully) provides the reader a starting place for her own experimentations.
- You're using a Unix-like environment and are comfortable using a command-line terminal and shell. If you're using Windows, you may want to examine my python web-dev box, a Vagrant virtual machine, to provide this environment.
- You have Python, virtualenv, virtualenvwrapper, and pip installed on your machine.
- You have installed Git and have created a GitHub account. I furthermore assume you have working knowledge of Git. GitHub's help pages may prove useful for many questions you may have.
- Fork my kfr2.github.com repository.
- Underneath the repository's settings, rename the forked repository to
- Open a terminal.
- Clone the repository to your machine with the command
git clone https://github.com/your_username/your_username.github.com
- Make a new virtualenv for the project by running
your_username.github.comas the virtualenv's default directory. When you next run
workon your_username.github.comto load the virtualenv, your shell will change its working directory to the
git checkout sourceto see the site's source files (rather than its compiled HTML files).
- Install the project's requirements:
pip install -r requirements.txt
- Download a Pelican theme and place it within a subdirectory of
themes. For instance, you can download my site's theme via
git clone https://github.com/kfr2/pelican-svbtle.git your_username.github.com/themes/pelican-svbtle
- Update the settings within
publishconf.py. You may find Pelican's settings documentation helpful.
- Update content within
content's subdirectories. For instance, you will likely want to delete any entries underneath
content/blogas well as modify
content/pagesto your liking.
- If you'd like to serve this site at something other than
content/extra/CNAMEto include the desired domain. See GitHub's "Setting up a custom domain with Pages" for further instructions.
- If you wish to run a development server to view your site and its changes, run the command
make devserver. The site should be accessible at http://localhost:8000. The development server can be stopped with the command
- When satisfied, commit your changes:
git commit -am "A description of your changes."
- Push your source file changes:
git push origin source
make githubto push your compiled source files to GitHub. You will likely receive an email notification regarding your page's build status.
workon your_username.github.comto activate the project's virtualenv.
python new_post.pyto create a new post.
- Edit the post in your favorite text editor.
- Examine the post in context of your website with
make devserver. Shut the server down with
- When satisfied with the post, run
git commit -am "Message describing the post"
- Push the source changes with
git push origin source
- Push compiled files to your website with
My suggested workflow may not suit your needs or interests. Indeed, throughout the course of writing this post I realized how tedious it may be to setup a website using the methods outlined above — especially if one is unfamiliar with Git, GitHub, *nix, or Python. Thus, you may be interested in examining how the alternatives listed below fit your needs.
GitHub Pages Automatic Page Generator
GitHub allows one to create pages with an automatic generator for both her user (at
http://username.github.com) and individual projects (at
http://username.github.com/project-name). This could be much less maintenance than a Pelican-based approach as GitHub hosts Jekyll, the static website generator powering the automatic generator, and runs your site files through it when you push changes to the repository. In this situation, one will not need to have Python and the various Pelican dependencies installed. You may wish to view an example of Automatic Page Generator.
1. Create a public gist on Github with one or more Markdown-syntax files. 2. Note the gist ID number. It’s usually a longish number like 29388372. 3. View your writing presented nicely at gist.io/gist-id-here
For reference, see the gist.io's example post. This method of content creation is incredibly rapid. However, it is designed for one-off posts as it does not currently provide a method for viewing multiple posts by the same author. If you like this style of content creation and wish gist.io acted more like a regular blog engine (as well as allowed you to customize its appearance), it may be worth forking gist.io's source into something that links to your gists and hosting it on a service like Heroku.
Hopefully this article has enlightened you to how you may use a static website generator like Pelican to share your content with the world. No matter which generator you use to convert your writings to web pages, they will function similarly and should all serve to assist you in conveying your messages to the world. May your journeys be fruitful and intriguing.