Add docs

Author: recmo

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/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();

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]