A minimal Jekyll theme created for my blog - https://weixuanz.github.io.

• GitHub Pages compatible
• Optimised for speed (perfect score on PageSpeed Insight):
  • No JQuery
  • Minified HTML, CSS and JS
  • Asynchronous loading of non-critical CSS
  • Image lazy-loading
  • And more...
• Dark mode support, with animated transition
• Mobile friendly
• Tag system, with sorted tag clouds
• Ajax pagination
• Dynamic TOC
• Code listings with copy button
• RSS Feed and SEO
• Google Tag Manager

This repository is a clone of that for my website, with commits not related to the theme stripped out, also with modifications for generalisation. For the commenting system (not included in this theme), check out WeixuanZ/utterances. For Algolia search integration, WeixuanZ/search may be of interest.

• Installation
• Usage
  • Metadata
    • Navigation
    • Google Analytics (optional)
    • Font Awesome Kit (optional)
  • Layouts
    • Homepage
    • Blog Posts and Tag Pages
  • Customising
• Contributing
• Development
• License

If you are hosting your site on GitHub Pages, fork this repository and follow the Development setup instead, and rename it to <username>.github.io.

Alternatively, you can use remote_theme: weixuanz/simple-jekyll-theme by including a whitelisted gem called jekyll-remote-theme in your _config.yml, more details here. Note that you will need to include the default _config.yml entriely, since no configuration will be copied.

If you are not using GitHub pages, follow along. Add this line to your Jekyll site's Gemfile:

gem "simple-jekyll-theme"

And then execute:

$ bundle

Add this line to your Jekyll site's _config.yml:

theme: simple-jekyll-theme

Set the keys shown below with desired values:

permalink: pretty
title: Simple
author: W Zhang
tagline: "A minimal theme for blogs"
description: "Theme for my personal blog https://weixuanz.github.io"
url: "https://weixuanz.github.io/simple-jekyll-theme"  # no "/" at the end
lang: en
paginate: 5  # number of posts displayed on each page

Please note that since only key-value pairs in _config.yml are supported for pre-configuring, you may need to copy other values (e.g. plugins) from the default _config.yml in this repository manually. This behaviour is not consistent betweenn the gem and jekyll-remote-theme approaches. If something is not showing up, copy the entire default _config.yml. More informationn at pre-configuring theme-gems.

The _config.yml in this repository cannot purely contain key-value pairs because of the demo website.

Add names and paths under the navigation key in _config.yml to specify links in the navigation bar:

navigation:
  - name: Home
    link: /
  - name: About
    link: /about/

Note that the default permalink setting is pretty, you need to include permalink: pretty in _config.yml, and use the corresponding format when specifying navigation.

You can add Google Analytics through Google Tag Manager, add the following to your _config.yml:

google-tag-manager-id: GTM-xxxxxx

You can use the Font Awesome Kit instead of using the default hardcoded svg icons. This is useful if you want to include more icons than the ones defined in ./_includes/icons.html. You can register for a free kit at https://fontawesome.com.

font-awesome-kit: xxxxxxxxxx

If the above is specified in _config.yml, svg icon definitions will not be included, and <i /> will be used.

The theme provides four layouts:

• default.html — The base layout that lays the foundation for subsequent layouts, can be used for standalone pages.
• home.html — The layout for your landing-page / home-page / index-page. [More Info]
• post.html — The layout for your posts.
• tagpage.html — The layout for your tag pages.

Note that you would have to include the corresponding font-matter to specify the layout, since Jekyll’s default settings cannot be overridden by a theme-config.

Add the following to index.html of your site:

---
layout: home
title: Home
pagination:
  enabled: true
---

Please note that for pagination to work, the index file must be in .html instead of .md.

All content from the file (if there's any) will be injected above the generated post list by the home layout. This will allow you to include non-posts related content to be published on the landing page.

Name your blog posts as yyyy-mm-dd-name.md and put them in ./_posts/. Some important front matter configurations are listed below:

---
layout: post
title: Example
author: W Zhang
description: This is an example post
tag: [example, jekyll]
toc: true
mathjax: true
---

A rather unfortunate result of supporting GitHub Pages is that the fantastic Jekyll tag gems cannot be used. I wrote a Python script ./scripts/tag_generator.py based on Long Qian's fantastic solution. You will need to download it separately if you are using the gem approach, perhaps using:

wget https://raw.githubusercontent.com/WeixuanZ/simple-jekyll-theme/master/scripts/tag_generator.py

You can use the provided ./scripts/pre-commit git hook for automatic execution, or use yarn run tag if you cloned this repository.

On the other hand, if you prefer doing it manually, you simply need to create .md files under ./tag/. For example, ./tag/jekyll.md for a tag named jekyll may contain the following:

---
layout: tagpage
title: "Tag: jekyll"
tag: jekyll
---

Other than blockquotes, this theme also provides .hint and .danger, with blue and red left border respectively. They are implemented as classes on top of blockquotes, you can use the Kramdown syntax:

> This is a hint
{:.hint}

The theme also includes the lazysizes package, to enable lazy-loading of images, use data-src instead of src, and add lazyload class.

<figure>
    <img data-src="/assets/images/example.png" class="lazyload">
    <figcaption>Example figure</figcaption>
</figure>

To override the default structure and style, simply create the concerned directory at the root of your site, copy the file you wish to customise to that directory, and then edit the file.

The files you may be particularly interested in:

.
├── _includes
│   ├── footer.html
│   ├── head.html         -> <head /> in default layout
│   ├── custom-head.html  -> placeholder for adding more metadata to <head />, e.g. png favicons
│   └── comment.html      -> placeholder for commenting system
├── _sass
│   ├── blog.scss         -> critical and non-critical styles related to blog posts, e.g. toc
│   ├── code.scss
│   ├── definitions.scss  -> colour, font and mixin definitions
│   ├── main.scss         -> critical styles
│   ├── mobile.scss       -> media queries
│   └── print.scss
└── assets
    └── js
        ├── main.js       ┬> note that the minified versions xxxx.min.js are used
        └── pagination.js ┘

Bug reports and pull requests are welcome on GitHub at https://github.com/weixuanz/simple-jekyll-theme. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To set up your environment to develop this theme, run bundle install and yarn install.

To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using the theme. Add pages, documents, data, etc. like normal to test the theme's contents. As you make modifications to the theme and content, the site will regenerate and you should see the changes in the browser after a refresh, just like normal.

I recommend using Google's Closure-compiler for minifying JavaScripts. If you have Homebrew installed, it's simply brew install closure-compiler. For automatic execution, you can also use the provided git hook.

When the theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to the theme-gem, please edit the regexp in simple-jekyll-theme.gemspec accordingly.

The theme is available as open source under the terms of the MIT License. Please link to this repository in the footer if you overwrite the default one.

By default, svg icons used (in ./_includes/icons.html) are from Font Awesome, which are licensed under the Creative Commons Attribution 4.0 International license. No modifications were made.

Amazing open-source code used:

• Source-codes included in this gem:
  • Monokai theme colour definitions
  • Theme switching script by Koos Looijesteijn (Modified)
  • jekyll-compress-html MIT
  • jekyll-toc MIT (Modification merged upstream)
• Dependencies:
  • JS libraries:
    • Clipboard.js
    • lazysizes
  • Jekyll plug-ins:
    • jekyll-seo-tag
    • jekyll-sitemap
    • jekyll-feed