Site setup with GitHub Pages

This first post is more of a reminder for me how to setup a basic website with GitHub Pages, but hopefully it can be of interest/use to others!

We start off with the most basic example which should only take a couple of minutes to set up after installing the proper Ruby and Jekyll libraries (see here).

We then go over setting up the popular Minimal Mistakes theme, which this website is based off of. Finally, we go over the setup for the template you see here!

If you have the Ruby and Jekyll libraries installed, you can skip directly to the setup for this website. However, it is recommended to go over the Jekyll documentation if you are new to it.

Let me know if you have any problems with the steps detailed here! I hope others will find this post to be a useful reference :)

Quick setup for blogging

Simple Jekyll setup after setting up Ruby environment (modified from here):

gem install jekyll bundler

# create website at current directory
# this will auto-generate a few files for a simple website
jekyll new . 

# build and display
bundle exec jekyll serve

# Now browse to http://localhost:4000

Now it is possible to make blog posts by using the correct file naming convention.

The generated site will be placed in a directory called _site. It’s probably a good idea to add this to your .gitignore file, which may automatically be done.

In the generated _config.yml file, feel free to modify the entries, such as title, to customize your website!

Minimal mistakes template

We now switch to this tutorial for a nice template. It is assumed that the previous steps have been completed.

Updating Gemfile

As we will be using GitHub Pages, we will replace gem "jekyll" in Gemfile with:

gem "github-pages", group: :jekyll_plugins

Run bundle update from the terminal to make sure that all gems are properly installed.

Modifying generated content

• Replace the generated index.md file with this HTML file.
• Remove about.md.
• For any files in _posts_, change the layout entry at the top to posts.

Edit configuration file _config.yml

• Copy or re-create this _config.yml file.
• Make sure the following line is there and uncommented:

remote_theme           : "mmistakes/minimal-mistakes"

As before, feel free to modify the entries to customize your website. You can refer to here for an in-depth explanation of each setting.

Adding masthead (top navigation bar) and pages

Create a _data directory in your project and add a _navigation.yml file inside. As seen in the example _navigation.yml file, you can place multiple title entries which will correspond to the options on the “masthead” at the top of your webpage. Clicking a particular option will navigate to the url specified by the url entry in the _navigation.yml file.

For example, the following entry

- title: "Quick-Start Guide"
  url: https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/

will create a “Quick-Start Guide” option at the masthead to go the link specified by the url entry.

It also possible to link internally to your own pages such as an “About” page:

- title: "About"
  url: /about/

where /about/ should be a permalink within your website structure, such as at the header of the file _pages/about.md.

See here for clear instructions on how to create pages.

Finer detail customization

For stylistic modifications, it is very likely you will need to change the default theme.

This can be done by copying the following directories from here (you can download the repository as a .zip file, extract, and then copy the desired folders):

_includes
_layouts
_sass

At this link, they describe some styles modifications that can be made.

Setting font and font size

Issue #1352.

Line 78 in _pages.scss.

Adjusting text width for posts and pages

Perhaps you find the default text width to be too narrow. This can be adjusted by going inside the _sass files.

Inside _sass/minimal-mistakes/_page.scss, the following variables can be adjusted to vary the column widths

$right-sidebar-width-narrow: 400px !default;
$right-sidebar-width: 250px !default;
$right-sidebar-width-wide: 500px !default;

Otherwise, inside _sass/minimal-mistakes/_page.scss (for pages) and _sass/minimal-mistakes/_archive.scss (for posts), remove the padding-right line completely (when underneath a width line):

@include breakpoint($large) {
    float: right;
    width: calc(100% - #{$right-sidebar-width-narrow});
    padding-right: $right-sidebar-width-narrow;
}

Related GitHub issues: #1265 and #1373.

This template!

The original code for the template used in this website can be found here. I find this to be a fantastic template due to its simplistic design and the well-designed publications page. More about the template can be read in the blog of the creator.

Basic steps for reproducing and customizing

Copy/clone/fork the repository, navigate to the directory from a Terminal, and run bundle update to make sure that all gems are properly installed.

For editing the author info, you’ll again have to dig into the _config.yml file.

To modify the “CV” (“Curriculum” in the original code) and “Publications” pages, you’ll have to edit the correspondings HTML files in _layout. Very basic HTML coding is needed, so not to worry!

Adding new pages (such as “Teaching” in this website) simply requires adding a markdown file in the main directory and adding the appropriate link in the _config.yml file, e.g.:

links:
  - title: CV
    url: /cv/
  - title: Publications
    url: /publications/
  - title: Projects
    url: /projects/
  - title: Teaching
    url: /teaching/
  - title: Blog
    url: /blog/

You can remove the Twitter feed by removing the following snippet in _layouts/home2.html:

<a class="twitter-timeline" href="https://twitter.com/jponttuset" data-widget-id="338001751854686210">Tuits de @jponttuset</a>
      <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+"://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>

Or to add your own timeline, replace the above snippet with the HTML code generated by following these instructions.