Add optional math support for markdown

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 0.20.0 (unreleased)
 
+- Add a `math` option in the `[markdown]` section in `config.toml` to render `$` and `$$` delimited math blocks. This is disabled by default.
+
 ## 0.19.2 (2024-08-15)
 
 - Fix some of YAML date parsing
@@ -72,7 +74,7 @@ feed_filenames)
 - `get_file_hash` is removed, use `get_hash` instead. Arguments do not change
 - Replace libsass by a Rust implementation: [grass](https://github.com/connorskees/grass). See https://sass-lang.com/documentation/breaking-changes
 for breaking changes with libsass: look for "beginning in Dart Sass"
-- Merge settings for the default language set in the root of `config.toml` and in the `[languages.{default_lang}]` section. 
+- Merge settings for the default language set in the root of `config.toml` and in the `[languages.{default_lang}]` section.
 This will error if the same keys are defined multiple times
 - Code blocks content are no longer included in the search index
 - Remove built-ins shortcodes
@@ -193,9 +195,9 @@ any pages related to that taxonomy
   object
   3. Search settings are now language specific
   4. Translations are now nested in the languages table
-- Paths unification: 
+- Paths unification:
   1. `get_url` does not load automatically from the `static` folder anymore
-  2. New path resolving logic for all on-disk files: replace `@/` by `content/`, trim leading `/` and 
+  2. New path resolving logic for all on-disk files: replace `@/` by `content/`, trim leading `/` and
      search in $BASE_DIR + $path, $BASE_DIR + static + $path and $BASE_DIR + content + $path
   3. `get_file_hash` now returns base64 encoded hash by default
   4. all functions working on files can now only load files in the Zola directory
@@ -240,7 +242,7 @@ any pages related to that taxonomy
 - Add a `[markdown]` section to `config.toml` to configure rendering
 - Add `highlight_code` and `highlight_theme` to a `[markdown]` section in `config.toml`
 - Add `external_links_target_blank`, `external_links_no_follow` and `external_links_no_referrer`
-- Add a `smart_punctuation` option in the `[markdown]` section in `config.toml` to turn elements like dots and dashes 
+- Add a `smart_punctuation` option in the `[markdown]` section in `config.toml` to turn elements like dots and dashes
 into their typographic forms
 - Add iteration count variable `nth` for shortcodes to know how many times a shortcode has been invoked in a given
 content
@@ -267,7 +269,7 @@ content
 ### Breaking
 
 - All paths like `current_path`, `page.path`, `section.path` (except colocated assets) now have a leading `/`
-- Search index generation for Chinese and Japanese has been disabled by default as it leads to a big increase in 
+- Search index generation for Chinese and Japanese has been disabled by default as it leads to a big increase in
 binary size
 
 ### Other

components/config/src/config/markup.rs

@@ -45,6 +45,8 @@ pub struct Markdown {
     pub external_links_no_referrer: bool,
     /// Whether smart punctuation is enabled (changing quotes, dashes, dots etc in their typographic form)
     pub smart_punctuation: bool,
+    /// Whether to enable latex math rendering
+    pub math: bool,
     /// Whether footnotes are rendered at the bottom in the style of GitHub.
     pub bottom_footnotes: bool,
     /// A list of directories to search for additional `.sublime-syntax` and `.tmTheme` files in.
@@ -208,6 +210,7 @@ impl Default for Markdown {
             external_links_no_follow: false,
             external_links_no_referrer: false,
             smart_punctuation: false,
+            math: false,
             bottom_footnotes: false,
             extra_syntaxes_and_themes: vec![],
             extra_syntax_set: None,

components/markdown/src/markdown.rs

@@ -439,6 +439,9 @@ pub fn markdown_to_html(
     if context.config.markdown.smart_punctuation {
         opts.insert(Options::ENABLE_SMART_PUNCTUATION);
     }
+    if context.config.markdown.math {
+        opts.insert(Options::ENABLE_MATH);
+    }
 
     // we reverse their order so we can pop them easily in order
     let mut html_shortcodes: Vec<_> = html_shortcodes.into_iter().rev().collect();

components/markdown/tests/markdown.rs

@@ -133,6 +133,15 @@ fn can_use_smart_punctuation() {
     insta::assert_snapshot!(body);
 }
 
+#[test]
+fn can_use_math() {
+    let mut config = Config::default_for_test();
+    config.markdown.math = true;
+    let body =
+        common::render_with_config(r#"Test inline $\sum_{e_k} \pi^i$ math."#, config).unwrap().body;
+    insta::assert_snapshot!(body);
+}
+
 #[test]
 fn can_use_external_links_options() {
     let mut config = Config::default_for_test();

components/markdown/tests/snapshots/markdown__can_use_math.snap

@@ -0,0 +1,6 @@
+---
+source: components/markdown/tests/markdown.rs
+expression: body
+snapshot_kind: text
+---
+<p>Test inline <span class="math math-inline">\sum_{e_k} \pi^i</span> math.</p>

docs/content/documentation/getting-started/configuration.md

@@ -86,7 +86,7 @@ feed_filenames = ["atom.xml"]
 hard_link_static = false
 
 # The default author for pages
-author = 
+author =
 
 # The taxonomies to be rendered for the site and their configuration of the default languages
 # Example:
@@ -142,6 +142,10 @@ external_links_no_referrer = false
 # For example, `...` into `…`, `"quote"` into `“curly”` etc
 smart_punctuation = false
 
+# Whether math delimitered by `$` and `$$` are rendered into `<span class="math math-inline">`
+# and `<span class="math math-display">` respectively.
+math = false
+
 # Whether to set decoding="async" and loading="lazy" for all images
 # When turned on, the alt text must be plain text.
 # For example, `![xx](...)` is ok but `![*x*x](...)` isn’t ok
@@ -210,7 +214,7 @@ index_format = "elasticlunr_javascript"
 [translations]
 
 # Additional languages definition
-# You can define language specific config values and translations: 
+# You can define language specific config values and translations:
 # title, description, generate_feeds, feed_filenames, taxonomies, build_search_index
 # as well as its own search configuration and translations (see above for details on those)
 [languages]