{"id":15288584,"url":"https://github.com/weixuanz/simple-jekyll-theme","last_synced_at":"2026-01-05T02:54:35.019Z","repository":{"id":56895774,"uuid":"299075184","full_name":"WeixuanZ/simple-jekyll-theme","owner":"WeixuanZ","description":"A minimal Jekyll theme for blogs","archived":false,"fork":false,"pushed_at":"2021-04-19T10:37:18.000Z","size":355,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-06T06:04:45.046Z","etag":null,"topics":["github-pages","jekyll","jekyll-blog","jekyll-theme","ruby-gem","theme"],"latest_commit_sha":null,"homepage":"https://weixuanz.github.io/simple-jekyll-theme","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WeixuanZ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-27T16:42:57.000Z","updated_at":"2024-06-12T07:25:04.000Z","dependencies_parsed_at":"2022-08-20T17:10:27.610Z","dependency_job_id":null,"html_url":"https://github.com/WeixuanZ/simple-jekyll-theme","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeixuanZ%2Fsimple-jekyll-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeixuanZ%2Fsimple-jekyll-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeixuanZ%2Fsimple-jekyll-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeixuanZ%2Fsimple-jekyll-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WeixuanZ","download_url":"https://codeload.github.com/WeixuanZ/simple-jekyll-theme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245212303,"owners_count":20578443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-pages","jekyll","jekyll-blog","jekyll-theme","ruby-gem","theme"],"created_at":"2024-09-30T15:50:04.283Z","updated_at":"2026-01-05T02:54:34.945Z","avatar_url":"https://github.com/WeixuanZ.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Simple](/docs/head.png)\n\n\u003cp align=\"center\"\u003e\n    \u003ca aria-label=\"build\" href=\"https://github.com/WeixuanZ/simple-jekyll-theme/actions\" target=\"_blank\"\u003e\n      \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/workflow/status/weixuanz/simple-jekyll-theme/Gem%20Publish?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"version\" href=\"https://github.com/WeixuanZ/simple-jekyll-theme/blob/master/CHANGELOG.md\"\u003e\n      \u003cimg alt=\"Version\" src=\"https://img.shields.io/github/package-json/v/weixuanz/simple-jekyll-theme?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"license\" href=\"#license\" target=\"_blank\"\u003e\n      \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/github/license/weixuanz/simple-jekyll-theme?style=flat-square\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nA minimal Jekyll theme created for my blog - https://weixuanz.github.io.\n\n* GitHub Pages compatible\n* Optimised for speed (perfect score on PageSpeed Insight):\n    * No JQuery\n    * Minified HTML, CSS and JS\n    * Asynchronous loading of non-critical CSS\n    * Image lazy-loading\n    * And more...\n* Dark mode support, with animated transition\n* Mobile friendly\n* Tag system, with sorted tag clouds\n* Ajax pagination\n* Dynamic TOC\n* Code listings with copy button\n* RSS Feed and SEO\n* Google Tag Manager\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://weixuanz.github.io/simple-jekyll-theme\"\u003e\u003cimg alt=\"theme screenshot\" src=\"/screenshot.png\" width=\"400\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nThis 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.\n\n* [Installation](#installation)\n* [Usage](#usage)\n    * [Metadata](#metadata)\n        * [Navigation](#navigation)\n        * [Google Analytics \\(optional\\)](#google-analytics-optional)\n        * [Font Awesome Kit \\(optional\\)](#font-awesome-kit-optional)\n    * [Layouts](#layouts)\n        * [Homepage](#homepage)\n        * [Blog Posts and Tag Pages](#blog-posts-and-tag-pages)\n    * [Customising](#customising)\n* [Contributing](#contributing)\n* [Development](#development)\n* [License](#license)\n\n\n## Installation\n\n\u003e If you are hosting your site on GitHub Pages, fork this repository and follow the [Development](#development) setup **instead**, and rename it to `\u003cusername\u003e.github.io`.\n\u003e\n\u003e 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.\n\nIf you are not using GitHub pages, follow along. Add this line to your Jekyll site's `Gemfile`:\n\n```ruby\ngem \"simple-jekyll-theme\"\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\n## Usage\n\nAdd this line to your Jekyll site's `_config.yml`:\n\n```yaml\ntheme: simple-jekyll-theme\n```\n\n### Metadata\n\nSet the keys shown below with desired values:\n\n```yaml\npermalink: pretty\ntitle: Simple\nauthor: W Zhang\ntagline: \"A minimal theme for blogs\"\ndescription: \"Theme for my personal blog https://weixuanz.github.io\"\nurl: \"https://weixuanz.github.io/simple-jekyll-theme\"  # no \"/\" at the end\nlang: en\npaginate: 5  # number of posts displayed on each page\n```\n\nPlease 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).\n\n\u003e The `_config.yml` in this repository cannot purely contain key-value pairs because of the demo website.\n\n\n#### Navigation\n\nAdd names and paths under the `navigation` key in `_config.yml` to specify links in the navigation bar:\n\n```yaml\nnavigation:\n  - name: Home\n    link: /\n  - name: About\n    link: /about/\n```\n\nNote that the default permalink setting is `pretty`, you need to include `permalink: pretty` in `_config.yml`, and use the corresponding format when specifying `navigation`.\n\n\n#### Google Analytics (optional)\n\nYou can add Google Analytics through Google Tag Manager, add the following to your `_config.yml`:\n\n```yaml\ngoogle-tag-manager-id: GTM-xxxxxx\n```\n\n#### Font Awesome Kit (optional)\n\nYou 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.\n\n```yaml\nfont-awesome-kit: xxxxxxxxxx\n```\n\nIf the above is specified in `_config.yml`, svg icon definitions will not be included, and `\u003ci /\u003e` will be used.\n\n\n### Layouts\n\nThe theme provides four layouts:\n\n* `default.html` — The base layout that lays the foundation for subsequent layouts, can be used for standalone pages.\n* `home.html` — The layout for your landing-page / home-page / index-page. [[More Info](#homepage)]\n* `post.html` — The layout for your posts.\n* `tagpage.html` — The layout for your tag pages.\n\n**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.**\n\n\n#### Homepage\n\nAdd the following to `index.html` of your site:\n\n```yaml\n---\nlayout: home\ntitle: Home\npagination:\n  enabled: true\n---\n```\n\nPlease note that for pagination to work, the index file must be in `.html` instead of `.md`.\n\nAll 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.\n\n\n#### Blog Posts and Tag Pages\n\nName your blog posts as `yyyy-mm-dd-name.md` and put them in `./_posts/`. Some important front matter configurations are listed below:\n\n```yaml\n---\nlayout: post\ntitle: Example\nauthor: W Zhang\ndescription: This is an example post\ntag: [example, jekyll]\ntoc: true\nmathjax: true\n---\n```\n\nA 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:\n\n```bash\nwget https://raw.githubusercontent.com/WeixuanZ/simple-jekyll-theme/master/scripts/tag_generator.py\n```\n\nYou can use the provided `./scripts/pre-commit` git hook for automatic execution, or use `yarn run tag` if you cloned this repository.\n\nOn 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:\n\n```yaml\n---\nlayout: tagpage\ntitle: \"Tag: jekyll\"\ntag: jekyll\n---\n```\n\nOther 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:\n\n```markdown\n\u003e This is a hint\n{:.hint}\n```\n\nThe 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.\n\n```html\n\u003cfigure\u003e\n    \u003cimg data-src=\"/assets/images/example.png\" class=\"lazyload\"\u003e\n    \u003cfigcaption\u003eExample figure\u003c/figcaption\u003e\n\u003c/figure\u003e\n```\n\n\n### Customising\n\nTo 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.\n\nThe files you may be particularly interested in:\n\n```\n.\n├── _includes\n│   ├── footer.html\n│   ├── head.html         -\u003e \u003chead /\u003e in default layout\n│   ├── custom-head.html  -\u003e placeholder for adding more metadata to \u003chead /\u003e, e.g. png favicons\n│   └── comment.html      -\u003e placeholder for commenting system\n├── _sass\n│   ├── blog.scss         -\u003e critical and non-critical styles related to blog posts, e.g. toc\n│   ├── code.scss\n│   ├── definitions.scss  -\u003e colour, font and mixin definitions\n│   ├── main.scss         -\u003e critical styles\n│   ├── mobile.scss       -\u003e media queries\n│   └── print.scss\n└── assets\n    └── js\n        ├── main.js       ┬\u003e note that the minified versions xxxx.min.js are used\n        └── pagination.js ┘\n```\n\n## Contributing\n\nBug 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](https://contributor-covenant.org) code of conduct.\n\n\n## Development\n\nTo set up your environment to develop this theme, run `bundle install` and `yarn install`.\n\nTo 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.\n\nI 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.\n\nWhen 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.\n\n## License\n\nThe theme is available as open source under the terms of the [MIT License](/LICENSE.md). Please link to this repository in the footer if you overwrite the default one.\n\nBy default, svg icons used (in `./_includes/icons.html`) are from Font Awesome, which are licensed under the [Creative Commons Attribution 4.0 International license](https://creativecommons.org/licenses/by/4.0/). No modifications were made.\n\nAmazing open-source code used:\n* Source-codes included in this gem:\n    * [Monokai theme colour definitions](https://gist.github.com/asaaki/1007420)\n    * [Theme switching script by Koos Looijesteijn](https://gist.github.com/kslstn/20f654fd27eb29619040c74fa6526919) (_Modified_)\n    * [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) MIT\n    * [jekyll-toc](https://github.com/allejo/jekyll-toc) MIT (_Modification merged upstream_)\n* Dependencies:\n    * JS libraries:\n        * [Clipboard.js](https://clipboardjs.com)\n        * [lazysizes](https://github.com/aFarkas/lazysizes)\n    * Jekyll plug-ins:\n        * [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag)\n        * [jekyll-sitemap](https://github.com/jekyll/jekyll-sitemap)\n        * [jekyll-feed](https://github.com/jekyll/jekyll-feed)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweixuanz%2Fsimple-jekyll-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweixuanz%2Fsimple-jekyll-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweixuanz%2Fsimple-jekyll-theme/lists"}