1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
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/.
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
```
Features
--------
### 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`.
### Posts feed
See [feed/index.html] for an example of how to easily create a paginated post
feed.
Basically, just include posts/posts.html.
[feed/index.html]: feed/index.html
### Category pages
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/categories.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 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
### 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
Include custom CSS stylesheets in the header & custom JavaScript files in the
footer by specifying the `page.custom_css` and `page.custom_js` arrays.
They will be picked up from the root "assets/css" and "assets/js" directories
respectively (unless the URL is absolute).
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.
1. Simply copying the latest versions of the relevant files would lose their
history.
2. Heavily rewriting repository history using `git filter-branch` or something
like this is painfully hard to get right for me.
Development
-----------
### Bootstrap theme
At one point I decided to bundle a modified version of Bootstrap 3.4 with the
theme.
One thing I found annoying about the unmodified Bootstrap is the small font
size & the insanely large headers.
I used the [customization tool] with a [custom config] to download a modified
Boost version and included it in the assets/bootstrap directory.
[customization tool]: https://getbootstrap.com/docs/3.4/customize/
[custom config]: assets/bootstrap/config.json
TODO: port the theme to Bootstrap 4/5/whatever?
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.
[LICENSE.txt]: LICENSE.txt
|
