New Website

Welcome to my new website! This is a little project that my wife and I worked on together and we had a lot of fun doing it. My wife deserves all the credit for the fantastic artwork and logos. Read on if you are interested in how to do the rest.

Contents

• Site Generator
• Theme
• Getting Sassy
• Deployment

Site Generator

To generate this site I use Jekyll, a static site generator written in Ruby. This is an excellent option if, like me, you like writing in markdown and want an automated tool to convert markdown to static HTML.

To get started with Jekyll I recommend following their Step by Step tutorial.

Jekyll sites generally have the following structure:

├── _config.yml
├── _data
│   └── navigation.yml
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   └── 2020-03-07-my-first-post.md
├── _sass
│   ├── _base.scss
│   └── _layout.scss
├── _site
├── assets
│   ├── css
│   └── images
├── Gemfile
└── index.html

Here is a very brief rundown of what each of these components do.

• _config.yml: The configuration file for your site. Here you define some variables, list plugins and set the corresponding parameter values.
• _data: In this directory you can create yaml files to define additional variables.
• _includes: This is simply a place for defining HTML snippets that can be used in your layouts. e.g. Define behaviour for the header/footer for your site.
• _layouts: This is where you define layouts for your site pages. In other words, these are HTML files that define how a given page is laid out.
• _posts: This one is pretty clear, it’s a directory where you store your posts. The best part being that they can be markdown files!
• _sass: This is the most important section if you want to customise the look of your website. In this directory you define all your style sheets using Sass (more on this in below).
• _site: This is where the final static HTML files generated by Jekyll are stored. In general you won’t need to touch anything here, but it can be useful to see what’s going on as you are building your website.
• assets: In this directory you can store e.g. images, CSS files and java scripts.
• Gemfile: The Gemfile is used to fix package versions and dependencies for your website.
• index.html: This is where you set the content for your home page. It can be defined in either HTML or markdown. Other static pages are similarly defined in the root directory.

One of the benefits of using Jekyll is the ability to visualise your website before you deploy. All you need to do is:

• Install your site dependencies:

bundle install

• Launch the Jekyll server:

bundle exec jekyll serve

Theme

If you want to get your website up and going as quick as possible the best option is to use one of the many Jekyll themes. If, however, you want to fully customise your site then be prepared for a lot more work!

I decided to go for the latter option. Fortunately, I did not have to start from scratch. After learning the basics of Jekyll, I downloaded the Cayman theme to use as a template. I essentially dissected this theme to figure out how all the pieces work.

Getting Sassy

Most of the work of getting your site to look the way you want it to is in defining the style sheets. This means learning how to write Cascading Style Sheets (CSS). One of the most exciting things I discovered while working on this project was Syntactically Awesome Style Sheets (Sass) and Sass certainly is awesome!

To get started with SASS check of their guide.

Sass has several very cool features including nesting and mixins. Mixins allow you define reusable pieces of CSS that you can include in your Sass files (.scss).

Here is a quick example of how to add a shadow to a container (something I used extensively on my site).

@mixin shadow {
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
}

.post-container {
  @include shadow;
}

Once you get comfortable with Sass, the rest is just patience. You will define the layouts for each type of page (I ended up with 7 different layouts). In my opinion this is made easier by breaking your HTML into pieces (that you keep in _includes). Similarly, you can break your Sass files into pieces that can import each other.

Deployment

Finally, once your website is ready for the world to see it, you can deploy it. In principle, you can do this on any server you like, but GitHub is ideally suited for hosting static HTML sites.

You can host your site on any GitHub repository you have access to by simply creating a branch called gh-pages, but if this is going to your main website you should probably create a new repository called [Your Username].github.io. Anything you host on the master branch of this repository will be visible at https://[Your Username].github.io/.

You can add CI tests for your website on Travis CI by adding a .travis.yml file following the steps on the Jekyll website.

Note: If you have any trouble getting htmlproofer to work with arguments try the following.

install:
  - bundle install

script:
  - bundle exec jekyll build
  - bundle exec htmlproofer --disable-external --empty_alt_ignore ./_site