Creating an Engineering Blog with GitHub Pages
This post explains how to create a free blog site using GitHub pages which has built in markdown support from Jekyll. Includes setting up local environment for OSX or Windows.
So You Want to Setup A Blog
As part of our platform uplift we wanted to start giving back to the community and sharing our experiences, which means we need a blog. GitHub pages is a great way to setup a free static website and it includes Jekyll which provides a great way to setup a blog. Your content is just static markdown pages which you commit to Github, just like code.
We could have gone with something more elaborate like WordPress or Drupal with a database behind it and the related complications but this seems a natural and great starting point for a web development team. The team starts using Github and the Github flow branching strategy just as they will be doing with code.
Creating a Site
You can create a site with no local development by creating and editing the site directly on Github by adding a new file. GitHub runs Jekyll when you commit then it deploys your site.
Personally I created the site initially following the excellent guide by Jonathon Mcglone. Then to customise, add Bootstrap etc I pulled down the project locally, installed Jekyll and used Visual Studio Code, on my Mac.
I am not going to add a full tutorial when as above there is the great one already from Jonathon Mcglone and another from Barry Clark. For the markdown syntax see https://help.github.com/articles/basic-writing-and-formatting-syntax.
Running Jekyll Locally
As I said above you can do this without installing or running locally just by committing to GitHub. However if you want to do some customisation and see how it looks before pushing then you need to install Jekyll. We run it with the watch option so any changes will be built automatically then you just have to refresh the browser to see them. This means you can live preview your blogs.
The easiest way to do this is by installing Docker, no need to install anything else. In the root of your project create a docker-compose file as below then in a terminal from the project root run the command `docker-compose up` and Jekyll will run connected live to your code. Any changes will be automatically detected and redeployed as above.
Explanation
- We are using the official Jekyll docker image which has Jekyl fully installed and ready to run. When you first run this file it will be downloaded from [docker hub](https://hub.docker.com/r/jekyll/jekyll/).
- We give a name to our running docker image so we can identify it when cleaning up.
- Line 7 we mount our current directory as a volume or drive available within the container. So Jekyll can see our files.
- Line 10 we run the Jekyll command line using the mapped location and watch for files changes.
- Line 11 We make the port specified in our _config file available form outside the docker image. Left side is port for the outside world, right is the one the app is running on within the image.
Styling
We wanted to add bootstrap styling and our own stylesheet. You can take a look at our code.
Bootstrap
Update your _layouts/default.html file.
Next is and our logo so inside the assets folder (which is copied to the _site folder) I added an images folder with our favicon and logo then added this in the header.
<link rel=’shortcut icon’ href=’/assets/images/favicon.ico’ type=’image/x-icon’ />then the logo svg in the Body
<a href=”/” class=”navbar-brand”>
<img src=’/assets/images/cardano_logo.svg’ />
</a>SCSS
You can also use SASS or SCSS files as Jekyll has a built in compiler. Simply rename the main.css file to main.scss. That’s it. Jekyll will place a compiled file in _site\assets\css\main.css.
Code Highlighting
Jekyll has pigments built in so you can download lots of css files which can change your code styling, such as demisx.github.io. You also might want to get rid of the borders by adding this to the end of the file.
.highlight pre { border: none }Complete Source Code
Our complete site with all of the above is available on our Github at https://github.com/cardano/cardano.github.io.
You can see our Cardano Engineering site running at https://cardano.github.io
