A really quick howto !
Set up a github.io page
To create your github user page, head over to github and create two new repositories - username.github.io-src and username.github.io - as explained here. The src repository will hold the sources of your blog and the username.github.io repository will contain the output html files that pelican generates. Since we're going to add the output directory as a submodule, initialise it with a readme - I can't seem to add a bare git repository as a submodule in a simple way.
On Fedora, this is a very very simple command:
sudo dnf install python-pelican
If you aren't on a Fedora system, you'll have to install these packages another way, like with pip. I'd suggest using a virtualenv, but it's up to you:
virtualenv blog_virt cd blog_virt source bin/activate pip install pelican ghp-import #then change to your git repository and continue
Set up the blog with pelican
Pelican provides an excellent quickstart command. Double check that you're working in the source git repository using:
git remote -v
Then, clone the output repository as a git submodule:
git submodule add firstname.lastname@example.org:sanjayankur31/sanjayankur31.github.io.git output #replace the URL with the correct one.
It'll ask you various questions, just answer them. If you're using the latest version of Pelican, it'll ask you if you want to use github pages and so on.
Open the publishconf.py file and set the DELETE_OUTPUT_DIRECTORY variable to False. Otherwise, each time you publish, it deletes your submodule - we don't want that.
There are various tweaks and tips mentioned here that you should look at. One of the more handy ones is the addition of a newpost command in the Makefile.
Build, commit, push, and you're done!
Once done, you build your blog and check if everything is OK:
make html; make serve #creates a demo site and serves it on localhost:8000
This runs a local webserver on port 8000 - direct your browser there to see the results of your work! If everything is OK, generate the website, add your files, commit them, and push to your repositories:
make publish #creates the complete site # Commit to the output submodule first cd output git add . git commit -m "First post." git push -u origin master # The commit the source repository cd .. echo '*.pyc' >> .gitignore #don't need pyc files git add . git commit -m "First commit." git push -u origin master # Sources committed
That's all! Head over the username.github.io and see the new site you've just created!
Caveats and customisations
Everything can be pretty much customised in Pelican. To start with, there are a set of themes that you can choose from. On top of that, you even have a set of plug-ins that help you add various functionalities to your site. Of course, you can write your own or customise existing plugins and themes.
There's a tool called ghp-pages that the pelican documentation refers to, but as of Pelican 3.6.3 which Fedora 22 features, the tool doesn't work as described in the documentation. It's why I used the submodule method.