Jekyll theme
============
[](https://github.com/egor-tensin/jekyll-theme/actions/workflows/ci.yml)
My [Jekyll] theme.
I use it for [egor-tensin.github.io], [blog], [sorting-algorithms],
[wireguard-config].
[Jekyll]: https://jekyllrb.com/
[egor-tensin.github.io]: https://egor-tensin.github.io/
[blog]: https://egor-tensin.github.io/blog/
[sorting-algorithms]: https://egor-tensin.github.io/sorting-algorithms/
[wireguard-config]: https://egor-tensin.github.io/wireguard-config/
Preview
-------
An example website can be viewed at https://egor-tensin.github.io/jekyll-theme/.
Usage
-----
Use the `jekyll-remote-theme` plugin.
Put this in your \_config.yml:
```
plugins:
- jekyll-remote-theme
# Other plugins...
remote_theme: egor-tensin/jekyll-theme
# Preferably, pin the exact commit:
#remote_theme: egor-tensin/jekyll-theme@COMMIT_HASH
```
Configuration
-------------
The complete list of configuration options follows.
Put it in \_config.yml and adjust how you see fit.
```
settings:
project:
name: Test project
# The following settings are picked up from GitHub by default.
description: This is a test project
license: MIT License
license_file: LICENSE.txt
author:
name: John Doe
email: John.Doe@example.com
navbar:
hide: false
# Only relevant if the project's on GitHub.
github:
link: GitHub
icon: globe
sidebar:
hide: false
# If you want to enable Google Analytics, optional:
ga_tag: X-XXXXXXXXXX
```
Features
--------
* [Layouts](#layouts)
* [Navbar](#navbar)
* [Sidebar](#sidebar)
* [Feed](#feed)
* [Categories](#categories)
* [Code snippets](#code-snippets)
* [Shell commands](#shell-commands)
* [Typesetting math](#typesetting-math)
* [Custom CSS & JavaScript](#custom-css--javascript)
### Layouts
* `plain`: navbar at the top + footer at the bottom.
* `default`: same as plain, but with a sidebar on the right.
* `page`: same as default, but with the page's header.
* `post`: same as default, but with the post's header and publication date.
### Navbar
Hide the navbar by setting either `site.settings.navbar.hide` or
`page.navbar.hide` to `true`.
Put a page on the navbar by setting `page.navbar.link` to `true` or a custom
HTML string.
Pages are sorted in the ascending order of `page.navbar.priority`.
If a page on the navbar is paginated, set `page.navbar.paginated` to `true` so
that it doesn't appear more than once.
You can add a glyphicon to the navbar link by settings `page.navbar.icon` to
something like "home" or "envelope" (or [any other glyphicon]).
[any other glyphicon]: https://getbootstrap.com/docs/3.4/components/#glyphicons
#### GitHub link
If you use `jekyll-github-metadata` (you do if you use the `github-pages` gem),
a link to the GitHub repository is added at the end of the navbar.
Customize the link text and the icon by setting
`site.settings.navbar.github.link` and `site.settings.navbar.github.icon`
accordingly.
Hide the link by setting `site.settings.navbar.github` to `false`.
### Sidebar
Hide the sidebar by setting either `site.settings.sidebar.hide` or
`page.sidebar.hide` to `true`.
The sidebar includes two entries by default: "About" and "Latest posts".
Hide them individually by setting `sidebar.{about,latest_posts}.hide` to `true`
(either under `site.settings` or `page`).
Add content to the sidebar by putting it in your _includes/custom-sidebar.html.
### Feed
See [feed/index.html] for an example of how to easily create a paginated post
feed.
Basically, just include posts/feed.html.
[feed/index.html]: feed/index.html
### Categories
See [life/index.html] or [work/index.html] for examples of how to create
category pages, with a list of posts belonging to the category.
Basically, just include categories/category.html and set the `category`
parameter to the category's name.
[life/index.html]: life/index.html
[work/index.html]: work/index.html
If you want to create a page with a list of all categories and the posts
belonging to them, see [archive/index.html] for an example.
Simply including categories/all.html should do the job.
[archive/index.html]: archive/index.html
### Code snippets
See [this post][snippets] for an example of how to conveniently embed code
snippets in your pages.
Basically, you need to put something like this in the front matter:
[snippets]: _posts/2021-04-09-snippets.md
```
snippets_root_directory: snippets
snippets_language: c++
snippets:
hello:
- hello.hpp
- hello.cpp
world:
- world.hpp
- world.cpp
```
And then you can just format an entire section of snippets using a single
`include`:
```
{% include jekyll-theme/snippets/section.html section_id='hello' %}
```
The line above would output both hello.hpp and hello.cpp to the page.
Code snippets can be hidden in collapsible panels.
See [this post][collapsible] for an example.
[collapsible]: _posts/2021-04-10-collapsible.md
### Shell commands
See [this post][shell] for an example of adding pretty shell commands and their
outputs to a page.
The gist is:
[shell]: _posts/2022-03-21-shell.md
```
{% include jekyll-theme/shell.html cmd='echo 123' out='123' %}
```
### Typesetting math
[MathJax] can be used to typeset mathematics using LaTeX.
To use MathJax, set `mathjax` to `true` in page's front matter.
Then you can do things like this:
```
This is an inline formula: $$y = kx + b$$.
This is a formula in a separate block:
$$
y = kx + b
$$
```
[MathJax]: https://www.mathjax.org/
Behind the scenes, Kramdown transforms these to `\(...\)` and `\[...\]`
sequences, to be processed by MathJax.
See [this post][mathjax post] for a usage example.
[mathjax post]: _posts/2021-04-08-mathjax.md
### Custom CSS & JavaScript
Add custom `` tags to the header by adding them either to:
* `site.settings.links` in _config.yml (the new links will be added to all
pages),
settings:
links:
- {rel: stylesheet, href: 'https://example.com/global-link.css'}
- {rel: stylesheet, href: 'assets/css/local-link.css'}
* `page.links` in a page's front matter (will be added to this page only).
---
links:
- {rel: stylesheet, href: 'https://example.com/global-link.css'}
- {rel: stylesheet, href: 'assets/css/local-link.css'}
---
You can also add custom `