A minimalistic Jekyll theme created for my blog - 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 my fork of Utterances.
Installation¶ ↑
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 useremote_theme: WeixuanZ/simple-jekyll-theme
by including a whitelisted gem called jekyll-remote-theme in your_config.yml
, more details here.
Add this line to your Jekyll site's Gemfile
:
gem "simple-jekyll-theme"
And then execute:
$ bundle
Usage¶ ↑
Add this line to your Jekyll site's _config.yml
:
theme: simple-jekyll-theme
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.
Metadata¶ ↑
Overwrite the default values shown below by providing alternatives in your _config.yml
.
title: Simple Jekyll Theme author: W Zhang tagline: "A minimalistic 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
Google Analytics (optional)¶ ↑
You can add Google Analytics through Google Tag Manager, add the following to your _config.yml
:
google-tag-manager-id: GTM-xxxxxx
Font Awesome Kit (optional)¶ ↑
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 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.
Navigation¶ ↑
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
, or use the corresponding format when specifying navigation
.
Homepage¶ ↑
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.
Blog Posts¶ ↑
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/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>
Customising¶ ↑
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 ┘
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub at 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.
Development¶ ↑
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.
License¶ ↑
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