blob: 188afe8705652a8c79097c5e2c63f4fefcaecbb4 (
plain) (
tree)
|
|
jekyll-theme
============
My [Jekyll] theme.
I use it for [egor-tensin.github.io], [blog], [sorting-algorithms].
[Jekyll]: https://jekyllrb.com/
[egor-tensin.github.io]: https://github.com/egor-tensin/egor-tensin.github.io
[blog]: https://github.com/egor-tensin/blog/tree/gh-pages
[sorting-algorithms]: https://github.com/egor-tensin/sorting-algorithms/tree/gh-pages
API
---
See the _config.yml files in the projects above to see which `site` values are
used.
Otherwise this theme is irrelevant for anybody but me of course, so it's not
worth documenting.
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` must be set to `null` in _config.yml in order to make
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
History
-------
This theme wasn't built from the ground up, it's a product of concurrent
evolution of my three Jekyll projects.
At one moment 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.
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
|
