Math Content Blocks

A WordPress plugin that adds a Math Formula block for rendering mathematical equations using MathJax.

Works standalone or as part of the cohesive trio: Markdown Importer + Code Content Blocks + Math Content Blocks. See Mermaid Content Blocks for diagram support.

Features

• Math Formula Block – Add mathematical notation directly in the WordPress block editor
• Multiple Input Formats – Support for TeX/LaTeX, AsciiMath, and MathML
• Live Editor Preview – See formula changes in real-time while editing
• Variable Color Rules – Highlight specific variables with custom colors
• MathJax 4 Rendering – Professional mathematical typesetting via CommonHTML output
• Shared Renderer API – window.MCBMathBlocks.renderAll() and window.MCBMathBlocks.renderBlock()
• Graceful Fallback – Source markup remains visible if JavaScript is disabled
• Accessibility – Semantic MathML for screen readers when possible

Installation

Via WordPress Plugin Directory (When Available)

1. Go to Plugins > Add New in your WordPress admin
2. Search for "Math Content Blocks"
3. Click Install Now and then Activate

Manual Installation

1. Download the plugin from the releases page
2. Upload the math-content-blocks folder to /wp-content/plugins/
3. Go to Plugins in WordPress admin and activate "Math Content Blocks"
4. You're ready to use the block!

Quick Start

1. Edit or create a post/page in WordPress
2. Click the + button to add a block
3. Search for "Math Formula" and insert the block
4. Choose your input format: TeX, AsciiMath, or MathML
5. Enter your formula
6. (Optional) Add variable color rules in the block settings
7. Publish!

Input Formats

TeX / LaTeX

The most common format for mathematical typesetting:

\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

Quadratic formula – Rendered beautifully with full support for symbols, fractions, exponents, and complex expressions.

\sum_{i=1}^{n} i = \frac{n(n+1)}{2}

Series summation – Using subscripts and superscripts.

\int_0^{\infty} e^{-x^2} \, dx = \frac{\sqrt{\pi}}{2}

Gaussian integral – With advanced operators like integrals.

AsciiMath

A more human-readable alternative to TeX:

sum_(i=1)^n i = (n(n+1))/2

Series summation – Using simple ASCII operators.

x = (-b +- sqrt(b^2 - 4ac)) / (2a)

Quadratic formula in AsciiMath – More intuitive for quick entry.

1/2 = 0.5

Presentation MathML

XML-based mathematical markup:

<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
  <mrow>
    <mi>E</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup>
  </mrow>
</math>

Einstein's mass-energy equivalence.

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mfrac>
    <mrow><mo>−</mo><mi>b</mi><mo>±</mo><msqrt><msup><mi>b</mi><mn>2</mn></msup><mo>−</mo><mn>4</mn><mi>a</mi><mi>c</mi></msqrt></mrow>
    <mrow><mn>2</mn><mi>a</mi></mrow>
  </mfrac>
</math>

See examples.md for more formula examples.

Variable Color Rules

Highlight specific variables with custom colors to enhance readability:

x = #d32f2f
y = #1976d2
z = #388e3c
\alpha = purple
\beta = orange

How it works:

• One rule per line in the format variable = color
• Use hex colors (#d32f2f) or CSS color names (purple, green, etc.)
• For TeX/LaTeX, color rules use conservative source transformation
• For MathML, color rules target matching <mi> elements
• AsciiMath supports variable coloring through TeX conversion

Example with Color Rules

% TeX formula:
y = mx + b

With rules:

y = #e91e63
m = #2196f3
x = #ff9800
b = #4caf50

The slope, intercept, variable, and result each appear in their assigned color.

Features When Used with Markdown Importer

When activated alongside Markdown Importer Blocks:

• Inline TeX delimiters ($...$ or \(...\)) automatically render with color rules
• Display TeX delimiters ($$...$$ or \[...\]) render as block formulas
• Fenced math blocks (```tex, ```asciimath, ```mathml) become colored blocks
• Global math settings apply to all formulas in the imported Markdown
• Variable color rules sync across all math expressions

Usage with Other Plugins

• Markdown Importer Blocks – Converts Markdown math expressions into rendered blocks
• Code Content Blocks – No direct interaction, but works well in technical documentation
• Mermaid Content Blocks – Complementary for content mixing formulas and diagrams

Content Security Policy

The plugin loads MathJax from cdnjs:

https://cdnjs.cloudflare.com/ajax/libs/mathjax/4.x.x/es5/tex-mml-chtml.min.js

CSP Configuration

If your WordPress site has a restrictive Content Security Policy (CSP), allow these sources:

script-src 'self' https://cdnjs.cloudflare.com

Alternatively, bundle MathJax locally and modify the mcb_register_block() function in math-content-blocks.php.

Security

Security Posture

• Output Escaping – All formulas are properly escaped before rendering
• Format Validation – Only valid TeX, AsciiMath, and MathML are processed
• KSES Filtering – MathML is sanitized before rendering
• No Code Execution – Math is rendered only, never executed
• Pinned Library Version – Uses MathJax 4, not a floating tag
• Color Filtering – Variable color values are validated and sanitized

Important Notes

• Authors who can edit posts can add math blocks
• Do not grant post editing privileges to untrusted users
• Formulas are stored as-is in post content
• MathML is sanitized before being passed to MathJax
• Always keep WordPress and MathJax updated

Testing

Running Tests Locally

From the plugin directory, run:

bash tools/smoke-test.sh

This validates:

• PHP syntax via php -l
• JavaScript syntax via node --check
• Requires php and node to be installed

Manual Testing

See tests/manual-test-plan.md for comprehensive testing procedures.

Requirements

• WordPress: 6.7 or later
• PHP: 7.4 or later
• Browser: Modern browser with ES6+ support

Versioning

This project follows Semantic Versioning:

• MAJOR – Breaking changes or significant new features
• MINOR – Backward-compatible new features
• PATCH – Bug fixes and security patches

License

This project is licensed under the MIT License – see the LICENSE file for details.

Support

For issues, feature requests, or questions:

• Open an issue on GitHub
• Check existing discussions

Credits

• Plugin author: Monotoba
• Uses MathJax for mathematical rendering
• Distributed via cdnjs CDN

Related Plugins

• Markdown Importer Blocks – Import Markdown and delegate code/math/diagrams to specialized plugins
• Code Content Blocks – Syntax-highlighted code blocks with 80+ languages
• Mermaid Content Blocks – Create diagrams and flowcharts

Use all four plugins together for a complete content creation system, or use Math Content Blocks standalone.

Changelog

1.0.0 (Initial Release)

• Math Formula block for WordPress block editor
• Support for TeX/LaTeX, AsciiMath, and MathML
• Variable color rule system for enhanced readability
• Shared renderer API via window.MCBMathBlocks
• Live editor preview with MathJax rendering