diff options
author | Thomas Letan <lthms@soap.coffee> | 2020-02-23 22:45:45 +0100 |
---|---|---|
committer | Thomas Letan <lthms@soap.coffee> | 2020-02-23 22:45:45 +0100 |
commit | 21da228358d9cb9c1129af5df9e81152d1238666 (patch) | |
tree | e51a167508652d5103e8d5fec5e2e7b9c205eed1 /site/cleopatra | |
parent | Move plugin-specific SASS rules in Soupault.org (diff) |
Explain how equations are rendered offline
Diffstat (limited to 'site/cleopatra')
-rw-r--r-- | site/cleopatra/Soupault.org | 77 | ||||
-rw-r--r-- | site/cleopatra/Theme.org | 6 |
2 files changed, 67 insertions, 16 deletions
diff --git a/site/cleopatra/Soupault.org b/site/cleopatra/Soupault.org index 7f73561..d6330d7 100644 --- a/site/cleopatra/Soupault.org +++ b/site/cleopatra/Soupault.org @@ -2,6 +2,8 @@ <h1><code>soupault</code> Configuration</h1> #+END_EXPORT +#+TOC: headlines 2 + * General Settings #+NAME: prefix @@ -289,20 +291,26 @@ https://code.soap.coffee/writing/lthms.git action = "replace_content" #+END_SRC -** Preprocessing Mathematics +** Rendering Equations Offline -#+BEGIN_SRC js :tangle scripts/katex.js -var katex = require("katex"); -var fs = require("fs"); -var input = fs.readFileSync(0); +*** User instructions -var html = katex.renderToString(String.raw`${input}`, { - throwOnError: false -}); +Inline equations written using the @@html:<span class="imath">\LaTeX</span>@@ +syntax can be rendered once and for all by ~soupault~. For instance, -console.log(html) +#+BEGIN_SRC html +<span class="imath">\LaTeX</span> #+END_SRC +This needs that you need to be able to use raw HTML in your input files. + +*** Implementation details + +We will use [[https://katex.org][@@html:<span class="imath">\KaTeX</span>@@]] to render equations +offline. @@html:<span class="imath">\KaTeX</span>@@ availability on most systems +is unlikely, but it is part of [[https://www.npmjs.com/package/katex][npm]], so we can define a minimal ~package.json~ +file to fetch it automatically. + #+BEGIN_SRC json :tangle package.json { "private": true, @@ -312,24 +320,67 @@ console.log(html) } #+END_SRC +We introduce a Makefile recipe to call ~npm install~. This command produces a +file called ~package-lock.json~ that we add to ~GENFILES~ to ensure @@html:<span +class="imath">\KaTeX</span>@@ will be available when ~soupault~ is called. + +#+BEGIN_REMARK +If ~Soupault.org~ has been modified since the last generation, Babel will +generate ~package.json~ again. However, if the modifications of ~Soupault.org~ +do not concern ~package.json~, then ~npm install~ will not modify +~package-lock.json~ and its “last modified” time will not be updated. This means +that the next time ~make~ will be used, it will replay this recipe again. As a +consequence, we systematically ~touch~ ~packase-lock.json~ to satisfy ~make~. +#+END_REMARK + #+BEGIN_SRC makefile :tangle soupault.mk package-lock.json : package.json @echo " init npm packages" @npm install + @touch $@ GENFILES += package-lock.json GENAUX += node_modules/ #+END_SRC -#+BEGIN_SRC sass :tangle site/style/plugins.sass -.imath - font-size: smaller +Once installed and available, @@html:<span class="imath">\KaTeX</span>@@ is +really simple to use. The following script reads (synchronously!) the standard +input, renders it using @@html:<span class="imath">\KaTeX</span>@@ and outputs +the resut to the standard output. + +#+BEGIN_TODO +This script should be generalized to handle both display and inline +mode. Currently, only inline mode is supported. +#+END_TODO + +#+BEGIN_SRC js :tangle scripts/katex.js +var katex = require("katex"); +var fs = require("fs"); +var input = fs.readFileSync(0); + +var html = katex.renderToString(String.raw`${input}`, { + throwOnError: false +}); + +console.log(html) #+END_SRC +We reuse once again the =preprocess_element= widget. The selector is ~.imath~ +(~i~ stands for inline in this context), and we replace the previous content +with the result of our script. + #+BEGIN_SRC toml :tangle soupault.conf -[widgets.math] +[widgets.inline-math] widget = "preprocess_element" selector = ".imath" command = "node scripts/katex.js" action = "replace_content" #+END_SRC + +The @@html:<span class="imath">\KaTeX</span>@@ font is bigger than the serif +font used for this website, so we reduce it a bit with a dedicated SASS rule. + +#+BEGIN_SRC sass :tangle site/style/plugins.sass +.imath + font-size: smaller +#+END_SRC diff --git a/site/cleopatra/Theme.org b/site/cleopatra/Theme.org index e013ee6..0f8d044 100644 --- a/site/cleopatra/Theme.org +++ b/site/cleopatra/Theme.org @@ -68,8 +68,8 @@ $text-fg-color: #505050 $primary-color: black $todo-bg: #e4d3b3 $todo-fg: #494130 -$remark-bg: #d4f2fc -$remark-fg: $text-fg-color +$remark-bg: #c5dbe2 +$remark-fg: #4d575e * box-sizing: border-box @@ -152,7 +152,7 @@ body#default color: $todo-fg .REMARK background: $remark-bg - background: $remark-fg + color: $remark-fg .TODO, .REMARK padding: 1em 1em 1em 1em |