Jekyll theme
My Jekyll theme.
I use it for tensin.name, blog, sorting-algorithms, wireguard-config.
Preview
An example website can be viewed at https://tensin.name/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
- Navbar
- Sidebar
- Feed
- Categories
- Code snippets
- Shell commands
- Typesetting math
- 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 includes the page title.nosidebar
: same as page, but without the sidebar.post
: same as default, but includes the post title 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).
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 3 entries by default: "latest posts", "about" and "links".
Hide them individually by setting sidebar.{latest_posts,about,links}.hide
to
true
(under either 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.
For this to work, you must enable the jekyll-paginate
plugin.
Don't forget to set site.paginate_path
to a proper URL (with the :num
placeholder) in _config.yml, like /feed/page:num/
or something.
Categories
See code/index.html or features/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.
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.
Code snippets
See this post 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_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 for an example.
Shell commands
See this post for an example of adding pretty shell commands and their outputs to a page. The gist is:
{% 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
$$
Behind the scenes, Kramdown transforms these to \(...\)
and \[...\]
sequences, to be processed by MathJax.
See this post for a usage example.
Custom CSS & JavaScript
Add custom <link>
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 <script>
tags in a similar way.
-
In _config.yml:
settings: scripts: - {src: 'https://example.com/global-script.js'} - {src: 'assets/js/local-script.js'}
-
In page's front matter:
--- scripts: - {src: 'https://example.com/global-script.js'} - {src: 'assets/js/local-script.js'} ---
Development
See DEVELOPMENT.md.
History
This theme wasn't built from the ground up, it's a product of concurrent
evolution of my three Jekyll projects.
At one point I got sick of the code duplication, so I just cloned the most
feature-reached project into this repository (tagged from_jekyll_project
),
and removed everything that wasn't theme-related.
Then I made some minor tweaks to make it work with the other two projects, and
voilĂ !
I thought about several alternatives to cloning the whole repository.
- Simply copying the latest versions of the relevant files would lose their history.
- Heavily rewriting repository history using
git filter-branch
or something like this is painfully hard to get right for me.
License
Distributed under the MIT License. See LICENSE.txt for details.
This theme is build upon the Twitter Bootstrap framework, which is also MIT Licensed and copyright 2015 Twitter.