diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..188afe8 --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +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 |