add README.mdtweaked

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