ExpressionEngine · intoeetive · May 27, 2025
diff --git a/docs/add-ons/math.md b/docs/add-ons/math.md
@@ -0,0 +1,48 @@
+<!--
+    This source file is part of the open source project
+    ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
+
+    @link      https://expressionengine.com/
+    @copyright Copyright (c) 2003-2020, Packet Tide, LLC (https://packettide.com)
+    @license   https://expressionengine.com/license Licensed under Apache License, Version 2.0
+-->
+
+# Math
+
+Math module provides template tag to perform mathematical operations on numbers. It can be used to calculate values, perform arithmetic operations, and format the results.
+
+Additionally to the module, there is also a [variable modifier](templates/variable-modifiers.md#math) that can be used to perform calculations on variables, and [`{layout:set:math}`](templates/layouts.md) tag.
+
+#### `{exp:math}`
+
+The tag can be used as single tag or as a tag pair. It accepts an `expression` parameter which is a mathematical expression to be evaluated.
+
+`expression` is the arithmetic expression to be evaluated. It can contain numbers and operators. It supports order of operation, parentheses, negation, basic arithmetic operations (`+`, `-`, `*`, `/`, `^`) and built-in functions.
+For example, you can use `{exp:math expression="10 + 5"}` to add 10 and 5, or `{exp:math expression="20 / 4"}` to divide 20 by 4.
+Of course, you can use variables or custom field values, for example `{exp:math expression="{variable_name} + 5"}`.
+
+The result returned is formatted number. Supported parameter for formatting are:
+
+- `decimals` - number of decimal places to round the result to
+- `decimal_point` - character to use as decimal point
+- `thousands_separator` - character to use as thousands separator
+
+When used as tag pair, the result is contained in `result` variable
+
+    {exp:math expression="{current_time}/10+5"}
+        {result}
+    {/exp:math}
+
+The list of built-in functions includes:
+- `abs(x)` - absolute value of x
+- `ceil(x)` - smallest integer greater than or equal to x
+- `floor(x)` - largest integer less than or equal to x
+- `round(x)` - round x to nearest integer
+- `sqrt(x)` - square root of x
+- `sin(x)` - sine of x (x in radians)
+- `cos(x)` - cosine of x (x in radians)
+- `tan(x)` - tangent of x (x in radians)
+- `arcsin(x)` - arcsine of x (result in radians)
+- `arccos(x)` - arccosine of x (result in radians)
+- `arctan(x)` - arctangent of x (result in radians)
+- `log(x)` - natural logarithm of x
diff --git a/docs/templates/layouts.md b/docs/templates/layouts.md
@@ -87,7 +87,7 @@ Notice that the layout is a [hidden template](templates/overview.md#hidden-templ
 
 You can set variables in your templates that can later be used in your layouts. For instance you can set the contents of the page title tag, or breadcrumb navigation, sidebar content, etc. The content can be set in one of three ways, depending on how you need to use it in your layout:
 
-#### {layout:set}
+#### `{layout:set}`
 
 **Setting** a variable works similarly to setting a string variable in a programming language, like JavaScript. The contents are set to the variable name you provide. In your template:
 
@@ -97,7 +97,22 @@ And then in the layout, wherever you need to use this variable, reference it by
 
     <title>{layout:title}</title>
 
-#### {layout:set:append}
+### `{layout:set:math}`
+
+If your variable needs to be a number, you can use the `{layout:set:math}` tag to perform simple math operations. This is useful for calculations that need to be done before outputting the value in your layout.
+For example, if you want to set a variable to the entry date divided by 1,000,000, you can do it like this:
+
+    {layout:set:math name='math'}{entry_date}/1000000{/layout:set:math}
+
+Then in your layout, you can use `{layout:math}` to output the result:
+
+    <p>Entry Date in Millions: {layout:math}</p>
+
+This will output the entry date divided by 1,000,000.
+
+The `{layout:set:math}` tag supports basic arthmetic operations, such as addition, subtraction, multiplication, division, as well as order of operation, parentheses, negation and some built-in functions - same as [Math Module](add-ons/math.md) and [`:math` variable modifier](templates/variable-modifiers.md#math).
+
+#### `{layout:set:append}`
 
 **Appending** a variable creates lists, and is similar to setting an array in a programming language, like JavaScript. Use this tag in a loop, when you want to capture the contents as individual items:
 
@@ -125,7 +140,7 @@ Like most pair variables, you have access to `{count}`, `{total_results}` as wel
       {/if}
     {/layout:titles}
 
-#### {layout:set:prepend}
+#### `{layout:set:prepend}`
 
 **Prepending** a variable works identical to `{layout:set:append}` above, except the new item gets pushed to the **front** of the list instead of added to the back.
 

diff --git a/docs/templates/variable-modifiers.md b/docs/templates/variable-modifiers.md
@@ -145,6 +145,24 @@ Note that all HTML formatting will be stripped out automatically before applying
     {excerpt:limit characters='20'}
     {!-- A discussion&#8230; --}
 
+### `:math`
+
+| Parameter            | Default   |                                                         |
+| -------------------- | --------- | ------------------------------------------------------- |
+| expression=          |           | second part of math expression                          |
+| function=            |           | additional function to apply to expression as a whole   |
+| decimals=            | `0`       | Number of decimal precision                 |
+| decimal_point=       | `.`       | character to use as decimal point |
+| thousands_separator= | `,`       | character to use as thousands separator |
+
+
+`expression` is the arithmetic expression to be evaluated, as addition to the variable.
+If your code is `{variable:math expression="/2"}`, the expression will be evaluated as `"{variable}/2"`, so if `{variable}` is `10`, the result will be `5`.
+Expression is required to start with a mathematical operand. You may only use numbers and operators in variable modifier's `expression` (no other variables).
+`function` is an additional function to apply to the resulting expression as a whole, such as `abs`, `ceil`, `floor`, `round`, `sqrt`, `sin`, `cos`, `tan`, `arcsin`, `arccos`, `arctan`, or `log`.
+
+See also [`{layout:set:math}`](templates/layouts.md) tag and [Math Module](add-ons/math.md).
+
 ### `:number_format`
 
 | Parameter              | Default   |                                             |