This is the seventh part of a multi-part series on how I built this site. In last post, we added two new pages to our site. An About page and a Book page. In this post, we are going to deploy the site to github pages. Github pages is a place on GitHub.com were documentation and static sites can be hosted.
Steps in this post
By the end of the post we are going to have a working static website hosted on GitHub pages. To accomplish this, we will complete the following steps:
- Pull the most recent version of the site from gitub
- Run pelican's
make htmlcommand to build the site and preview it with
- Modify the publishconf.py file to include our GitHub pages url and relative links
pelican content -s publishconf.pyto build a published version of the site in the output directory
- Add, commit and push the published contents to our master branch on GitHub
- Make a gh-pages branch in our staticsite repo on GitHub
git push origin gh-pagesto push the output directory to the gh-pages branch
- View the freshly published site!
OK, let's get started. Can't wait to see the published site live on GitHub pages.
Pull to the most recent version of the site from GitHub.com
Open a terminal and
cd to the
staticsite directory. Then activate the
(staticsite) virtual environment with
source activate staticsite. Once in the
(staticsite) environment, pull the most recent version of the site down from GitHub.com with
git pull origin master.
$ cd ~/Documents/staticsite $ conda activate staticsite (staticsite) $ git pull origin master
The staticsite directory should look something like this:
staticsite ├── LICENSE ├── Makefile ├── README.md ├── __pycache__ ├── _nb_header.html ├── content ├── develop_server.sh ├── fabfile.py ├── output ├── pelican-plugins ├── pelican-themes ├── pelican.pid ├── pelicanconf.py ├── publishconf.py └── srv.pid
Now we use the
On MacOS and Linux:
(staticsite) $ make html (staticsite) $ make serve
(staticsite) $ fab build (staticsite) $ fab serve
The demo version of our site can now be viewed by pointing a browser to:
ctr-c to stop the server.
Modify the publishconf.py file to use the github pages url
We need to edit the publishconf.py file to add our github pages url to
SITEURL and set
RELATIVE_URLS to True. The lines to change are:
#publishconf.py SITEURL = 'https://username.github.io/staticsite' RELATIVE_URLS = True
Make sure to set
username to your github user name. Setting
RELATIVE_URLS = False, the site looked terrible, had no formatting or css and none of the links worked. Setting
RELATIVE_URLS = True fixed the problem.
Create a published version of the site
Up to this point, we used the
make html command to build a demo version of the site. Now we are ready to publish the site. We publish the site by running the command:
(staticsite) $ pelican content -s publishconf.py
This creates a published version of the site with relative url's in the output directory.
Add, commit, push to the master branch on github
Before we can put the published version of the site up on github pages, we need to push the current version of the site up to the master branch.
(staticsite) $ git add . (staticsite) $ git commit -m "first published version" (staticsite) $ git push origin master
Create a gh-pages branch in our staticsite repo on github
ghp-import to post the contents of the output directory to the gh-pages branch
As shown in the Pelican documentation, you can use a Python package called
ghp-import to help posting the contents of the output directory to the gh-pages branch of our repo on github. If
ghp-import isn't installed yet, use
pip. Make sure you are in the
(staticsite) virtual environment when you run
(staticsite) $ pip install ghp-import
Now we'll use the ghp-import package to help us post the site. The command
ghp-import output will assign the contents of the output directory to the gh-pages branch of our local git repository. The we
push the contents of the local gh-pages branch up to the remote gh-pages branch on github.
(staticsite) $ ghp-import output (staticsite) $ git push origin gh-pages
I had trouble with this set of commands. Depending on which computer I was using, I would get the following error:
! [rejected] gh-pages -> gh-pages (fetch first) error: failed to push some refs to 'https://github.com/professorkazarinoff/staticsite.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
git stash and that didn't work. I also tried
git pull origin gh-pages but this ended up putting everything from the output directory into my root staticsite directory which made a big old mess.
The way I got around it was to use the
-f (force) flag. I don't think this is the most elegant or preferred way to get the contents of the output directory up to the gh-pages branch. I just don't really understand how
git works well enough to know how to get around the problem without a forced commit. If you get the error above try:
(staticsite) $ pelican content -s publishconf.py (staticsite) $ git add . (staticsite) $ git commit -m "published" (staticsite) $ git push origin master (staticsite) $ ghp-import output (staticsite) $ git push -f origin gh-pages
That has worked so far for me.
View the site on github pages.
Awesome! The site is now hosted for everyone to see on GitHub pages! Pretty cool right? Point a browser to the github pages url and take a look:
Change username to your GitHub user name. My site (the one that you are reading) is hosted here:
Thanks for reading to the end! It was quite a bit of work to get the site up and running, but I am pleased with the results. Now I need to read up on git . . .