From 333f8382c6f27ce92728098bc7035d49ec949f7c Mon Sep 17 00:00:00 2001
From: Jan Wille <mail@janwille.de>
Date: Wed, 5 Mar 2025 16:19:03 +0100
Subject: [PATCH] add documentation on how to customize mathjs

---
 astro.config.mjs                        |  1 +
 src/content/docs/guides/customMathJS.md | 56 +++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 src/content/docs/guides/customMathJS.md

diff --git a/astro.config.mjs b/astro.config.mjs
index 09b1aab..ab66ebf 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -48,6 +48,7 @@ export default defineConfig({
 							items: [
 								{ label: 'API', link: '/guides/api/' },
 								{ label: 'Advanced Use-Cases', link: '/guides/advancedusecases/' },
+								{ label: 'Customizing MathJS', link: '/guides/custommathjs/' },
 							],
 						},
 					],
diff --git a/src/content/docs/guides/customMathJS.md b/src/content/docs/guides/customMathJS.md
new file mode 100644
index 0000000..13573d9
--- /dev/null
+++ b/src/content/docs/guides/customMathJS.md
@@ -0,0 +1,56 @@
+---
+title: Customizing MathJS
+description: An example on how to import customizations into mathjs
+---
+
+You may find yourself wanting to add functionality to the [math view fields](/obsidian-meta-bind-plugin-docs/reference/viewfields/math/).
+And as they use [mathjs](https://mathjs.org/) internally, you actually can!
+
+## Importing new options into mathJS
+
+The mathjs library allows the user to define his own functions and constants, as described in [their documentation](https://mathjs.org/docs/core/extension.html).
+
+To leverage that, Meta Bind exposed its mathjs instance for you to modify.
+The most sensible place to do this, is inside a [JS-Engine startup-script](/obsidian-js-engine-plugin-docs/guides/startupscripts/).
+This ensures the modifications are loaded early and will be immediately available when the first documents gets rendered.
+
+:::caution
+Modifying mathJS via a js-engine codeblock inside a document may cause timing problems and is not recommended!
+:::
+
+### Adding a custom function `clamp`
+
+As an example, we defined the `clamp()` function, which is not part of default mathJS, but can be very helpful.
+It takes in three parameters, the current value, a minimum and a maximum. It returns the current value as long as its inside the range otherwise the boundary-value.
+
+```js
+clamp:  (val, min, max) => Math.min(Math.max(min, val), max)
+```
+
+Add this definitions inside a JavaScrypt file stored in you Vault and enable that file to be [run as a startup script](/obsidian-js-engine-plugin-docs/guides/startupscripts/).
+Inside the file you use the `mathJSimport(dict, options)` function from the API to import you definitions into mathjs.
+
+```js
+const mb = engine.getPlugin('obsidian-meta-bind-plugin').api;
+
+mb.mathJSimport({
+ // we define the function 'clamp'
+ clamp:  (val, min, max) => Math.min(Math.max(min, val), max),
+
+ // and a constant 'foo'
+ foo: 42
+});
+```
+
+Now you can create a view field using that function.
+This example will always display values between 0 and 10, even if `num` gets outside that range.
+
+```meta-bind
+VIEW[clamp({num}, 0, 10)]
+```
+
+You can also use the new constant `foo`. This will display 52:
+
+```meta-bind
+VIEW[foo + 10]
+```