Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/linjer/jekyll-katex
[DEPRECATED] Jekyll plugin for easy server-side math rendering via KaTeX
https://github.com/linjer/jekyll-katex
github-pages jekyll jekyll-katex jekyll-plugin katex latex
Last synced: 4 days ago
JSON representation
[DEPRECATED] Jekyll plugin for easy server-side math rendering via KaTeX
- Host: GitHub
- URL: https://github.com/linjer/jekyll-katex
- Owner: linjer
- License: mit
- Created: 2016-10-03T01:22:32.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-05-16T19:11:02.000Z (9 months ago)
- Last Synced: 2025-01-21T00:13:17.589Z (12 days ago)
- Topics: github-pages, jekyll, jekyll-katex, jekyll-plugin, katex, latex
- Language: Ruby
- Homepage:
- Size: 322 KB
- Stars: 98
- Watchers: 3
- Forks: 8
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# jekyll-katex
[](https://travis-ci.com/linjer/jekyll-katex)
[](https://badge.fury.io/rb/jekyll-katex)
This is a [Jekyll](http://jekyllrb.com) plugin for performing compile-time math rendering via the [KaTeX](https://github.com/Khan/KaTeX) library.
KaTeX is a library for rending math on the web using LaTeX, similar to MathJax.
KaTeX differs from MathJax in that it displays faster rendering speed and renders to pure HTML rather than PNGs.
There are various resources in benchmarking and comparing their performance, for more info, [start here](https://khan.github.io/KaTeX/).
Comes packaged with KaTeX `0.11.1` but you can specify a different version in your Jekyll `_config.yml` (see below).
## Installation
1. In your Jekyll project, add the plugin to your `_config.yml`, e.g.:
```yaml
plugins:
- jekyll-katex
```
2. Add `jekyll-katex` to your `gems.rb`/`Gemfile` plugin block:
```ruby
group :jekyll_plugins do
gem 'jekyll-katex'
end
```
Once done, execute `bundle install`.
3. Add KaTeX CSS and Fonts. Follow the installation instructions on the [KaTeX README](https://github.com/Khan/KaTeX).
You can skip including the `.js` file unless you want to do client-side in-browser rendering, as well.
Put the following (adjusting for your version) in your page headers:
```html
```
## Configuration
Supported configuration values, shown with default values:
```yml
katex:
js_path: "{{ Gem::lib_path }}/assets/js" # Path used to search for katex.min.js
rendering_options:
# Default KaTeX rendering options. See https://github.com/Khan/KaTeX#rendering-options
throw_error: true # throwOnError - set to false if you want rendering to output error as text rather than a build error
error_color: "#cc0000" # errorColor
```
## Usage
There are two liquid tags: `katex` and `katexmm`.
### katex
Use the `katex` liquid tag for LaTeX math equations like so:
```latex
{% katex %}
c = \pm\sqrt{a^2 + b^2}
{% endkatex %}
```
If you want the equation to be rendered in display mode (on its own line, centered, large symbols), just pass in the `display` parameter:
```latex
{% katex display %}
c = \pm\sqrt{a^2 + b^2}
{% endkatex %}
```
### katexmm
The `katex` liquid tag can be cumbersome, particularly if you have many inline blocks, which would need to be opened
and closed repeatedly, cluttering the source text. `katexmm` is an alternative that supports fenced math mode blocks
similar to standard latex:
```latex
{% katexmm %}
This is a mixed environment where you can have normal text and $c = \pm\sqrt{a^2 + b^2}$ fenced math. \$!
{% endkatexmm %}
```
* `$` for inline
* `$$` for display mode
* `\$` to escape `$` anywhere within the `katexmm` environment
## Development
```bash
$ bundle install
$ rake build
```
## Contributing
Feel free to open issues and pull requests.
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).