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

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.

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.