Hosting on Github Pages¶
Now that you've configured your Pelican site, created your content, viewed it, modified it, and are happy with it, you're ready to deploy your site somewhere viewable by the public.
Enter Github Pages.
Github provides free web hosting for static content for every single repository on Github. That means you can deploy your static site to Github Pages for no-hassle serverless web hosting.
(Also see the publish page of the pelican documentation.)
Differences between personal and project pages¶
In this walkthrough we assume the most common scenario of deploying a page on Github Pages for a project.
Setting up a personal page requires changing
branch names - see getting started
and the section on branches in particular.
The rest of the document will assume you are creating a project page.
Where is it?¶
Where do Github Pages live?
If your username is
username and your project name is
the Github source code is at:
and the Github Pages page will be at:
Initializing gh-pages branch¶
Before you begin, you have to create a
We want to create a new branch that is completely independent
of all other branches, because this branch will only contain
the static content of our website - no code, no readmes,
We want to link the
gh-pages branch, which will contain
the site's static content, with the
where Pelican generates all of its static content.
Remove the output directory, and clone a copy of your repo to the output directory:
$ cd pelican/ $ rm -rf output/ $ git clone https://github.com/username/projectname.git output $ cd output/
Now create a new orphan branch - that's the git terminology
for a branch that shares no history with any other branches.
$ git checkout --orphan gh-pages
Now all the content that was in the master branch
will show up as untracked files, because the new
gh-pages branch is totally empty.
Remove everything in the directory except
$ rm -rf * $ rm -rf .gitignore .gitmodules
Now add a simple "Hello world" page that we'll use to make sure our Github Pages page is being hosted correctly:
$ echo '<h2>Hello world!</h2>' > index.html $ git add index.html $ git commit index.html -m 'Initial commit of gh-pages branch' $ git push origin gh-pages
Now we have our intiial commit on the
Enabling Github Pages¶
We have one additional step to cover.
After we create the
we want to tell Github Pages that we have
web content on that branch that we want
Github to host.
Go to the repository settings,
and scroll down to the Github Pages
setting. Select the drop-down option
to host your Github Pages content
Now visit the URL to check out your Hello World page:
Adding the real content¶
We have a hello world page working, now let's add the real Pelican content.
Back in the
clean out the
(we'll be making everything from
$ rm -rf output/*
Don't remove the
output/ directory itself though!
Now make the content:
$ pelican content
Now add the content to the
and push it to Github to deploy it:
$ cd output/ $ git add -A . $ git commit -a -m 'Updating site' $ git push origin gh-pages
This will push the new static site (this time with
the Pelican output) to the
gh-pages branch on Github.
Sometimes the site updates really fast (few seconds),
sometimes it takes longer, but never more than about a minute.
Don't forget to add a link to your new page in the repository description (and in your README) to make it easier to find!