Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/weixuanz/simple-jekyll-theme
A minimal Jekyll theme for blogs
https://github.com/weixuanz/simple-jekyll-theme
github-pages jekyll jekyll-blog jekyll-theme ruby-gem theme
Last synced: about 1 month ago
JSON representation
A minimal Jekyll theme for blogs
- Host: GitHub
- URL: https://github.com/weixuanz/simple-jekyll-theme
- Owner: WeixuanZ
- License: mit
- Created: 2020-09-27T16:42:57.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2021-04-19T10:37:18.000Z (over 3 years ago)
- Last Synced: 2024-10-14T19:22:39.024Z (about 1 month ago)
- Topics: github-pages, jekyll, jekyll-blog, jekyll-theme, ruby-gem, theme
- Language: SCSS
- Homepage: https://weixuanz.github.io/simple-jekyll-theme
- Size: 347 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
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](https://github.com/WeixuanZ/utterances). For Algolia search integration, [WeixuanZ/search](https://github.com/WeixuanZ/search) may be of interest.
* [Installation](#installation)
* [Usage](#usage)
* [Metadata](#metadata)
* [Navigation](#navigation)
* [Google Analytics \(optional\)](#google-analytics-optional)
* [Font Awesome Kit \(optional\)](#font-awesome-kit-optional)
* [Layouts](#layouts)
* [Homepage](#homepage)
* [Blog Posts and Tag Pages](#blog-posts-and-tag-pages)
* [Customising](#customising)
* [Contributing](#contributing)
* [Development](#development)
* [License](#license)
## Installation
> If you are hosting your site on GitHub Pages, fork this repository and follow the [Development](#development) setup **instead**, and rename it to `.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](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-using-jekyll#adding-a-jekyll-theme-in-your-sites-_configyml-file). 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`:
```ruby
gem "simple-jekyll-theme"
```
And then execute:
```bash
$ bundle
```
## Usage
Add this line to your Jekyll site's `_config.yml`:
```yaml
theme: simple-jekyll-theme
```
### Metadata
Set the keys shown below with desired values:
```yaml
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](https://jekyllrb.com/docs/themes/#pre-configuring-theme-gems40).
> The `_config.yml` in this repository cannot purely contain key-value pairs because of the demo website.
#### Navigation
Add names and paths under the `navigation` key in `_config.yml` to specify links in the navigation bar:
```yaml
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`.
#### Google Analytics (optional)
You can add Google Analytics through Google Tag Manager, add the following to your `_config.yml`:
```yaml
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 https://fontawesome.com.
```yaml
font-awesome-kit: xxxxxxxxxx
```
If the above is specified in `_config.yml`, svg icon definitions will not be included, and `` will be used.
### Layouts
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](#homepage)]
* `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.**
#### Homepage
Add the following to `index.html` of your site:
```yaml
---
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 and Tag Pages
Name your blog posts as `yyyy-mm-dd-name.md` and put them in `./_posts/`. Some important front matter configurations are listed below:
```yaml
---
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](https://longqian.me/2017/02/09/github-jekyll-tag/). You will need to download it separately if you are using the gem approach, perhaps using:
```bash
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:
```yaml
---
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:
```markdown
> This is a hint
{:.hint}
```
The theme also includes the [lazysizes](https://github.com/aFarkas/lazysizes) package, to enable lazy-loading of images, use `data-src` instead of `src`, and add `lazyload` class.
```html
![]()
Example 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 -> in default layout
│ ├── custom-head.html -> placeholder for adding more metadata to