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
|
Egor's blog
===========
Egor's blog on programming.
Hosted on [GitHub Pages] at https://egor-tensin.github.io/blog/.
[GitHub Pages]: https://pages.github.com
Prerequisites
-------------
[Jekyll] is used to build a set of static HTML pages from a collection of
templates and resources.
[Bundler] is used to manage project's dependencies.
Make sure you have the `bundler` gem installed; project dependencies can then
be installed by executing
bundle install
in the project's root directory.
[Jekyll]: https://jekyllrb.com/
[Bundler]: http://bundler.io/
Usage
-----
To run a local web server, execute
bundle exec jekyll serve --watch --drafts --config _config.yml,_config_dev.yml
in the project's root directory.
You can then review your changes at http://localhost:4000/.
If you can't get Jekyll to properly `--watch` for file modifications on
Windows, try adding `--force_polling` to `jekyll`s options:
bundle exec jekyll serve --watch --force_polling --drafts --config _config.yml,_config_dev.yml
It might still not work though, but you can always re-run `jekyll` manually.
Note that `_config_dev.yml` is included to rewrite some of the `site` fields
from `_config.yml` during development.
In particular, it
* sets `minified_externals` to `false` so that the properly formatted versions
of external CSS stylesheets and JavaScript files are included instead of the
`min`ified versions,
* sets `include_comments` to `false` to exclude the Disqus comments section
from the posts,
* sets `baseurl` to an empty string so that the website can be accessed from
local web server's root directory (i.e. from http://localhost:4000/ instead of
http://localhost:4000/blog/).
### Access via file://
Jekyll doesn't provide native support for generating a static website which can
be browsed without running an instance of Jekyll's web server.
One easy workaround is to `wget` the website and convert the links:
wget --convert-links --recursive http://localhost:4000/
### 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/
#### GitHub workarounds
MathJax version 3 is used, which is unsupported by Kramdown (which produces
`<script type="math/tex; ..."` tags, suitable only for MathJax 2.
This is why `math_engine` is set to `null` in _config.yml, making Kramdown
output block formulas wrapped in `$$` and inline formulas in `$` respectively
([inside `<span class="kdmath">` elements][kramdown issue]).
Because if this, MathJax is additionally customized to recognize `$` as an
inline formula delimiter in _includes/common/mathjax.html.
GitHub Pages [helpfully overrides] the `math_engine` setting in your
_config.yml, hardcoding it to `mathjax` instead of `null` (there's a related
[pull request]).
I couldn't find a better way than to override the setting in the markdown
document itself using
{::options math_engine="+nil+" /}
[kramdown issue]: https://github.com/gettalong/kramdown/issues/342
[helpfully overrides]: https://help.github.com/en/articles/configuring-jekyll
[pull request]: https://github.com/github/pages-gem/pull/644
License
-------
Distributed under the MIT License.
See [LICENSE.txt] for details.
This website is build upon the Twitter Bootstrap framework, which is also MIT
Licensed and copyright 2015 Twitter.
[LICENSE.txt]: LICENSE.txt
|
