jektex 0.0.7 → 0.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +65 -42
- data/lib/jektex/jektex.rb +46 -12
- data/lib/jektex/version.rb +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 9405c84a9c1c4d137d5f9fe152943a72613a52fb741ea8dc3074c64368257b77
|
4
|
+
data.tar.gz: fcf023964df85b84be1ebab055fd778f923a63e3857facc083e451370168b366
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 1fda6a4eda19f919edc732da120ccfe2a20c520476465d53d79a98eb80087d94b438a84b863194009213781f5b15d180a5e7b22a6ca1eeb35e4bf3676da709c2
|
7
|
+
data.tar.gz: 7f3bd08cb26988e28c5ff910148404dcc0dee7f83478bbd04786aa5bf73ca5ea50fc93117e536c417549cb98f2192a27b20bdea99e598d3fcc15b49ef9b71208
|
data/README.md
CHANGED
@@ -1,26 +1,27 @@
|
|
1
1
|
[](https://rubygems.org/gems/jektex)
|
2
2
|
|
3
3
|
# Jektex
|
4
|
-
Jekyll plugin for blazing
|
5
|
-
Enjoy comfort of
|
4
|
+
A Jekyll plugin for blazing-fast server-side cached LaTeX rendering, with support for macros.
|
5
|
+
Enjoy the comfort of LaTeX and Markdown without cluttering your site with bloated JavaScript.
|
6
6
|
|
7
7
|
## Features
|
8
8
|
- Renders LaTeX formulas during Jekyll rendering
|
9
|
-
- Works without any
|
10
|
-
- Is faster than any other server
|
11
|
-
- Supports user
|
12
|
-
- Has I/O
|
13
|
-
-
|
14
|
-
- Is easy to setup
|
15
|
-
-
|
16
|
-
- Marks invalid
|
17
|
-
-
|
18
|
-
- Highly configurable but still having sensible defaults
|
9
|
+
- Works without any client-side JavaScript
|
10
|
+
- Is faster than any other server-side Jekyll LaTeX renderer
|
11
|
+
- Supports user-defined global macros
|
12
|
+
- Has I/O-efficient caching system
|
13
|
+
- Dynamically informs about the number of expressions during rendering
|
14
|
+
- Is very easy to setup
|
15
|
+
- Doesn't interfere with Jekyll workflow and project structure
|
16
|
+
- Marks invalid expressions in document, printing its location during rendering
|
17
|
+
- Is highly configurable with sensible defaults
|
19
18
|
- Makes sure that cache does not contain expression rendered with outdated configuration
|
20
19
|
|
21
20
|
## Usage
|
22
21
|
|
23
|
-
|
22
|
+
Jektex supports both the built-in Kramdown math notation, and the newer LaTeX-only math notation.
|
23
|
+
|
24
|
+
### Kramdown notation
|
24
25
|
**Inline formula**
|
25
26
|
Put formula between two pairs of dolar signs (`$$`) inside of paragraph.
|
26
27
|
```latex
|
@@ -29,7 +30,7 @@ adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliq
|
|
29
30
|
```
|
30
31
|
|
31
32
|
**Display formula**
|
32
|
-
Put formula between two pairs of dolar sings (`$$`) and surround it
|
33
|
+
Put formula between two pairs of dolar sings (`$$`) and surround it with two empty lines.
|
33
34
|
```latex
|
34
35
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
|
35
36
|
incididunt ut labore et dolore magna aliqua.
|
@@ -45,54 +46,74 @@ display mode?
|
|
45
46
|
This is how [kramdown](https://kramdown.gettalong.org/)(Jekyll's markdown parser) works
|
46
47
|
so I decided to respect this convention. It makes this plugin more consistent and universal._
|
47
48
|
|
49
|
+
|
50
|
+
### LaTex math mode notation
|
51
|
+
**Inline formula**
|
52
|
+
Put formula between two escaped brackets `\(` `\)`.
|
53
|
+
Its position in the text does not matter.
|
54
|
+
```latex
|
55
|
+
Lorem ipsum dolor sit amet, consectetur \(e^{i\theta}=\cos(\theta)+i\sin(\theta)\)
|
56
|
+
adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
57
|
+
```
|
58
|
+
|
59
|
+
**Display formula**
|
60
|
+
Put formula between two escaped square brackets `\[` `\]`.
|
61
|
+
Its position in the text does not matter.
|
62
|
+
```latex
|
63
|
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
|
64
|
+
incididunt ut labore et dolore magna aliqua.
|
65
|
+
|
66
|
+
\[ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) \]
|
67
|
+
|
68
|
+
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
|
69
|
+
ea commodo consequat.
|
70
|
+
```
|
71
|
+
|
48
72
|
### Config
|
49
|
-
Jektex si highly configurable
|
73
|
+
Jektex si highly configurable via your `_config.yml` file.
|
50
74
|
|
51
75
|
**Disabling cache**
|
52
|
-
You can disable caching with `disable_disk_cache = true` in `_config.yml`.
|
53
|
-
enabled by default.
|
76
|
+
You can disable caching with `disable_disk_cache = true` in `_config.yml`.
|
77
|
+
Caching is enabled by default.
|
78
|
+
You can find more information on [Jekyll's official website](https://jekyllrb.com/docs/configuration/options/).
|
54
79
|
|
55
80
|
**Setting cache location**
|
56
|
-
By default
|
57
|
-
deletion when you call `jekyll clean`.
|
58
|
-
|
59
|
-
`cache_dir` in `_config.yml`.
|
81
|
+
By default, Jektex cache will be saved in `.jekyll-cache` directory.
|
82
|
+
This results in its deletion when you call `jekyll clean`.
|
83
|
+
To prevent cache deletion or to change the cache location, you can specify `cache_dir` in `_config.yml`:
|
60
84
|
```yaml
|
61
85
|
# Jektex cache dir location
|
62
86
|
jektex:
|
63
87
|
cache_dir: ".jektex-cache"
|
64
88
|
```
|
65
89
|
|
66
|
-
**
|
67
|
-
By default
|
68
|
-
sometimes
|
69
|
-
|
70
|
-
You can use conventional wild cards using `*`. For example:
|
90
|
+
**Ignoring files**
|
91
|
+
By default, Jektex tries to render LaTeX in all files rendered by Jekyll.
|
92
|
+
This can sometimes be undesirable, for example when rendering an _RSS feed_ with excerpts containing LaTeX.
|
93
|
+
Jektex solves this by using the `ignore` option:
|
71
94
|
```yaml
|
72
95
|
# Jektex ignore files
|
73
96
|
jektex:
|
74
97
|
ignore: ["*.xml", "README.md", "_drafts/*" ]
|
75
98
|
```
|
76
99
|
|
77
|
-
|
78
|
-
in `_drafts` directory.
|
100
|
+
You can use conventional wild cards using `*`.
|
101
|
+
This example configuration ignores all `.xml` files, `README.md` and all files in the `_drafts` directory.
|
79
102
|
|
80
|
-
Another
|
81
|
-
post to `false`. For example:
|
103
|
+
Another way to ignore specific posts is setting the `jektex` attribute in front matter to `false`:
|
82
104
|
```yaml
|
83
105
|
---
|
84
|
-
|
106
|
+
ttle: "How Jektex works"
|
85
107
|
category: "Development"
|
86
108
|
jektex: false
|
87
109
|
layout: post
|
88
110
|
---
|
89
111
|
```
|
90
112
|
|
91
|
-
Setting `jektex` tag to `true` or not setting at all will result in
|
92
|
-
expressions in that post.
|
113
|
+
Setting `jektex` tag to `true` or not setting at all will result in Jektex rendering LaTeX expressions in that post.
|
93
114
|
|
94
|
-
**
|
95
|
-
You can define global macros
|
115
|
+
**Using macros**
|
116
|
+
You can define global macros:
|
96
117
|
```yaml
|
97
118
|
# Jektex macros
|
98
119
|
jektex:
|
@@ -100,8 +121,8 @@ jektex:
|
|
100
121
|
- ["\\Q", "\\mathbb{Q}"]
|
101
122
|
- ["\\C", "\\mathbb{C}"]
|
102
123
|
```
|
103
|
-
And yes you have to escape backlash(`\`) with another backlash.
|
104
|
-
[yaml
|
124
|
+
And yes, you have to escape the backlash (`\`) with another backlash.
|
125
|
+
This is due to the [yaml specification](https://yaml.org/).
|
105
126
|
|
106
127
|
**Complete examples**
|
107
128
|
Recommended config:
|
@@ -113,6 +134,7 @@ jektex:
|
|
113
134
|
- ["\\Q", "\\mathbb{Q}"]
|
114
135
|
- ["\\C", "\\mathbb{C}"]
|
115
136
|
```
|
137
|
+
|
116
138
|
Having no configuration is equivalent to this:
|
117
139
|
```yaml
|
118
140
|
jektex:
|
@@ -125,7 +147,7 @@ jektex:
|
|
125
147
|
This plugin is available as a [RubyGem](https://rubygems.org/gems/jektex).
|
126
148
|
|
127
149
|
**Using bundler**
|
128
|
-
Add
|
150
|
+
Add Jektex to your `Gemfile`:
|
129
151
|
```ruby
|
130
152
|
group :jekyll_plugins do
|
131
153
|
gem "jektex"
|
@@ -135,22 +157,23 @@ end
|
|
135
157
|
and run `bundle install`
|
136
158
|
|
137
159
|
**Without bundler**
|
138
|
-
|
160
|
+
Run `gem install jektex`
|
139
161
|
|
140
162
|
**After installation**
|
141
|
-
Add
|
163
|
+
Add Jektex to your plugin list in your `_config.yml` file
|
142
164
|
```yaml
|
143
165
|
plugins:
|
144
166
|
- jektex
|
145
167
|
```
|
146
168
|
|
147
|
-
and
|
169
|
+
and don't forget to add `katex.min.css` to you HTML head:
|
148
170
|
```html
|
149
171
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css" integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">
|
150
172
|
```
|
151
|
-
It is much better practice to download [**css** file](https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css) and load it as an asset from your server directly.
|
173
|
+
It is much better practice to download the [**css** file](https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css) and load it as an asset from your server directly.
|
152
174
|
You can find more information on [KaTeX's website](https://katex.org/docs/browser.html).
|
153
175
|
|
154
176
|
## Contributions and bug reports
|
155
177
|
Feel free to repost any bugs or even make feature request in [issues on official repository](https://github.com/yagarea/jektex/issues).
|
156
178
|
I am opened for pull requests as well.
|
179
|
+
|
data/lib/jektex/jektex.rb
CHANGED
@@ -7,7 +7,6 @@ PATH_TO_JS = File.join(__dir__, "/katex.min.js")
|
|
7
7
|
DEFAULT_CACHE_DIR = ".jekyll-cache"
|
8
8
|
CACHE_FILE = "jektex-cache.marshal"
|
9
9
|
KATEX = ExecJS.compile(open(PATH_TO_JS).read)
|
10
|
-
PARSE_ERROR_PLACEHOLDER = "<b style='color: red;'>PARSE ERROR</b>"
|
11
10
|
FRONT_MATTER_TAG = "jektex"
|
12
11
|
INDENT = " " * 13
|
13
12
|
|
@@ -48,7 +47,22 @@ def print_stats
|
|
48
47
|
$stdout.flush
|
49
48
|
end
|
50
49
|
|
51
|
-
|
50
|
+
#######################################################################################
|
51
|
+
# Render
|
52
|
+
|
53
|
+
def render_latex_notation(page)
|
54
|
+
# check if document is not set to be ignored
|
55
|
+
return page.content if !page.data || is_ignored?(page)
|
56
|
+
# convert HTML entities back to characters
|
57
|
+
post = HTMLEntities.new.decode(page.content.to_s)
|
58
|
+
# render inline expressions
|
59
|
+
post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, page.relative_path) }
|
60
|
+
# render display mode expressions
|
61
|
+
post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, page.relative_path) }
|
62
|
+
return post
|
63
|
+
end
|
64
|
+
|
65
|
+
def render_kramdown_notation(page)
|
52
66
|
# check if document is not set to be ignored
|
53
67
|
return page.output if !page.data || is_ignored?(page)
|
54
68
|
# convert HTML entities back to characters
|
@@ -79,8 +93,10 @@ def escape_method( type, expression, doc_path )
|
|
79
93
|
# create the cache directory, if it doesn't exist
|
80
94
|
begin
|
81
95
|
# render using ExecJS
|
82
|
-
result =
|
83
|
-
{ displayMode: is_in_display_mode,
|
96
|
+
result = KATEX.call("katex.renderToString", expression,
|
97
|
+
{ displayMode: is_in_display_mode,
|
98
|
+
macros: $global_macros
|
99
|
+
})
|
84
100
|
rescue SystemExit, Interrupt
|
85
101
|
# save cache to disk
|
86
102
|
File.open($path_to_cache, "w"){|to_file| Marshal.dump($cache, to_file)}
|
@@ -88,11 +104,16 @@ def escape_method( type, expression, doc_path )
|
|
88
104
|
raise
|
89
105
|
rescue ExecJS::ProgramError => pe
|
90
106
|
# catch parse error
|
91
|
-
puts "\e[31m
|
92
|
-
|
107
|
+
puts "\e[31m #{pe.message.gsub("ParseError: ", "")}\n\t#{doc_path}\e[0m"
|
108
|
+
# render expression with error highlighting enabled
|
109
|
+
return KATEX.call("katex.renderToString", expression,
|
110
|
+
{ displayMode: is_in_display_mode,
|
111
|
+
macros: $global_macros,
|
112
|
+
throwOnError: false
|
113
|
+
})
|
93
114
|
end
|
94
115
|
# save to cache
|
95
|
-
$cache[expression_hash] =
|
116
|
+
$cache[expression_hash] = result
|
96
117
|
# update count of newly generated expressions
|
97
118
|
$count_newly_generated_expressions += 1
|
98
119
|
print_stats
|
@@ -101,13 +122,24 @@ def escape_method( type, expression, doc_path )
|
|
101
122
|
end
|
102
123
|
|
103
124
|
Jekyll::Hooks.register :pages, :post_render do |page|
|
104
|
-
page.output =
|
125
|
+
page.output = render_kramdown_notation(page)
|
105
126
|
end
|
106
127
|
|
107
128
|
Jekyll::Hooks.register :documents, :post_render do |doc|
|
108
|
-
doc.output =
|
129
|
+
doc.output = render_kramdown_notation(doc)
|
130
|
+
end
|
131
|
+
|
132
|
+
Jekyll::Hooks.register :pages, :pre_render do |page|
|
133
|
+
page.content = render_latex_notation(page)
|
109
134
|
end
|
110
135
|
|
136
|
+
Jekyll::Hooks.register :documents, :pre_render do |doc|
|
137
|
+
doc.content = render_latex_notation(doc)
|
138
|
+
end
|
139
|
+
|
140
|
+
#######################################################################################
|
141
|
+
# SETTINGS AND INIT
|
142
|
+
|
111
143
|
Jekyll::Hooks.register :site, :after_init do |site|
|
112
144
|
# load jektex config from config file and if no config is defined make empty one
|
113
145
|
config = site.config["jektex"] || Hash.new
|
@@ -122,7 +154,7 @@ Jekyll::Hooks.register :site, :after_init do |site|
|
|
122
154
|
$cache = Hash.new
|
123
155
|
end
|
124
156
|
|
125
|
-
# check if cache is
|
157
|
+
# check if cache is disabled in config
|
126
158
|
$disable_disk_cache = site.config["disable_disk_cache"] if site.config.has_key?("disable_disk_cache")
|
127
159
|
|
128
160
|
# load macros
|
@@ -138,8 +170,8 @@ Jekyll::Hooks.register :site, :after_init do |site|
|
|
138
170
|
if $global_macros.empty?
|
139
171
|
puts "#{INDENT}LaTeX: no macros loaded"
|
140
172
|
else
|
141
|
-
puts "#{INDENT}LaTeX: #{$global_macros.size} macro"
|
142
|
-
|
173
|
+
puts "#{INDENT}LaTeX: #{$global_macros.size} macro" \
|
174
|
+
"#{$global_macros.size == 1 ? "" : "s"} loaded" +
|
143
175
|
($updated_global_macros.empty? ? "" : " (#{$updated_global_macros.size} updated)")
|
144
176
|
end
|
145
177
|
|
@@ -153,6 +185,8 @@ Jekyll::Hooks.register :site, :after_reset do
|
|
153
185
|
end
|
154
186
|
|
155
187
|
Jekyll::Hooks.register :site, :post_write do
|
188
|
+
# print stats once more to prevent them from being overwriten by error log
|
189
|
+
print_stats
|
156
190
|
# print new line to prevent overwriting previous output
|
157
191
|
print "\n"
|
158
192
|
# check if caching is enabled
|
data/lib/jektex/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: jektex
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.0.
|
4
|
+
version: 0.0.8
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Jan Černý
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2022-03-
|
11
|
+
date: 2022-03-22 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: execjs
|
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
127
127
|
- !ruby/object:Gem::Version
|
128
128
|
version: '0'
|
129
129
|
requirements: []
|
130
|
-
rubygems_version: 3.3.
|
130
|
+
rubygems_version: 3.3.8
|
131
131
|
signing_key:
|
132
132
|
specification_version: 4
|
133
133
|
summary: Highly optimized latex rendering for Jekyll
|