For the first article in the blog I'd like to explain the whole process that I made to set this website in GitHub Pages with Pelican a static site generator powered by Python.
This will be a kind of tutorial/guide thought the repository of this site.
Why Pelican and why GitHub Pages?
Because this website doesn't need a backend to fulfill its purpose, and because I don't want to mess around with a server service (for now), I decided to host it in GitHub Pages, a free service that uses your GitHub repository directly to generate a website. Now, there are a large amount of ways to make a blog like this one, and there are others blogging framewroks out there to use with GitHub Pages like Octopress, Hexo, Foundation, Jekyll (although Jekyll is the engine behind GitHub Pages), and pretty much anything that can produce HTML and CSS, even your bare hands with a Text Editor.
All of this frameworks have something different, but they make the same work in the end. So I chose Pelican simply because it's written in Python, and I love Python.
I assume that you're using Linux or an Unix-like operating system and Python 3.
With that being said let's get started.
Setting up our environment
First of all, we need to have order in our project so let's create a virtual environment, I use virtualenvwrapper it's a set of extensions that wrappers virtualenv and make it easier to use.
If you don't have them already just:
pip install virtualenv virtualenvwrapper
Create the virtual environment and switch to it:
mkvirtualenv --python=python3 blog
workon blog
Now install Pelican and Markdown if you're going to use it:
pip install pelican Markdown
We are going to use ghp-import later on so install it also:
pip install ghp-import
Creating our project
GitHub repository
Because this is a personal webpage I'm going to use a user GitHub Page, therefore we have to create a new repository with specific characteristics: - The name of the repository must be username.github.io where username is your username on GitHub. - As all the User GitHub Pages everything in your master branch will be used to make your page.
Now go to the folder where you want to place your project and clone the repository:
git clone https://github.com/username/username.github.io
Pelican project
Inside the project folder let's create a skeleton project:
pelican-quickstart
That command will ask you a set of questions for the configuration (you can change them later) of the page and it'll create a folder structure like this one:
blog
├── content/
├── output/
├── develop_server.sh
├── pelicanconf.py
└── publishconf.py
The pelicanconf.py file is where I'll put all the configuration, you can use specific settings for publish your site located in publishconf.py but I'm not going to use it.
Maybe the most important settings are the URL related ones, but you can do a lot of things in the pelicanconf.py file, feel free to go to the docs and check out all the possibilities.
Writing content
The part of writing is pretty simple, all the content of the site is written in Markdown and the files are going to be in the content folder. I separate the articles in category folders and the pages, the content that don't change very often (Bio, About), in its own folder.
You can see the metadata syntax for Markdown post in the pelican docs.
Theme and personalization
Now that we have some sort of content in the page we can visualize it, select a theme and tweaking a little bit.
I selected the Bootstrap 3 theme, just clone the repository:
git clone https://github.com/DandyDev/pelican-bootstrap3.git
And then point the THEME variable in your pelicanconf.py to /path/to/pelican-bootstrap3
Part of the beauty of Bootstrap 3 is that Daan Debie included all the Bootstrap 3 themes from
Bootswatch made by Thomas Park.
I which the Bootswatch theme to flatly by setting the BOOTSTRAP_THEME variable to the theme-name.
At this point the webpage looked really good, but checking out some examples I saw a terrific webpage called Beneath Data created by Tyler Hartley with a beautiful design and great content, so I use some of his design (hope he doesn't mind) and use it on my webpage.
If you want to change something of the theme just go to the theme folder and change it at will.
Adding third party services
To add Disqus comments, Google analytics, and AddThis
you have to create their respective accounts and then set the DISQUS_SITENAME, GOOGLE_ANALYTICS and ADDTHIS_PROFILE to the
code that each service provide you.
After that and with some luck everything should work automagically.
Hosting on GitHub Pages
The last part. The repository structure and the page hosting.
All the content and the settings will be in a source branch because the master branch is used to create the actual page.
In order to keep only the output/ folder in the master branch I used ghp-import, this little tool make a commit in a branch with only the content of a specific folder:
ghp-import -m "commit message" -b master output/
If no branch is specified the destination branch would be gh-pages that it's the branch used in a Project site GitHub Page.
After that you can just:
git push --all
And the page should be up and running.
Comments
comments powered by Disqus