Math notation

Foundry Core Math Notation V1 renders a conservative LaTeX-style math subset inside normal Markdown page bodies. Hugo transforms each expression to semantic MathML at build time. The published page needs no MathJax, KaTeX, browser JavaScript, CDN, or remote stylesheet.

Math Notation V1 was introduced in Foundry Core v0.1.40. The current production release is v0.1.42. Hugo v0.160.1 or newer is required.

Good Uses

Math notation is useful when a portable website needs readable equations alongside ordinary prose:

• science, engineering, and research explanations;
• education, course, and tutorial content;
• technical product documentation and API concepts;
• statistics, economics, finance, and measurement formulas;
• healthcare or policy explainers that need precise notation;
• matrices, vectors, integrals, sums, fractions, roots, Greek symbols, superscripts, and subscripts; and
• accessible, selectable equations that should remain in the repository and work without a managed service.

V1 is not a full TeX publishing system. It does not compile .tex documents, produce PDFs, load arbitrary packages, manage bibliographies, support site-defined macros, or provide equation numbering and cross-references.

Authoring Syntax

Use \( and \) for inline math:

Einstein's relation is \(E = mc^2\).

Use \[ and \] for display math:

\[
\int_0^1 x^2\,dx = \frac{1}{3}
\]

$$ is also supported for display math:

$$
\frac{a+b}{c}
$$

Single-dollar inline math is deliberately unsupported. A price such as $25 remains ordinary text. Math-looking text inside inline code or fenced code is also left unchanged.

Keep opening and closing display delimiters on their own lines. Do not begin a continuation line inside a display expression with a Markdown block marker such as - , + , * , or > ; keep the expression on one line or indent the continuation within the equation.

A complete portable example is examples/content-kits/article-math-notation.md. The compatibility proof is fixtures/compatibility/article-heavy-site/content/blog/foundry-fixture-article/index.md.

Rendering Contract

Core owns:

• the Goldmark passthrough delimiter configuration;
• layouts/_default/_markup/render-passthrough.html;
• strict transform.ToMath conversion with MathML output;
• stable .foundry-math--inline and .foundry-math--display wrappers;
• neutral responsive, print, and forced-colors styling;
• the effective-site authoring capability; and
• the read-only math validation report.

Invalid supported expressions fail the build with the stable FOUNDRY_MATH_INVALID marker and a source position. The public JSON validator normalizes that unstable Hugo output and does not expose the full expression. Unclosed and mismatched delimiters are caught by a source scan before the temporary validation build.

Display equations scroll within their own container when they are wider than a small viewport. They must not make the entire page scroll horizontally.

MathML remains semantic, selectable, zoomable, and available with JavaScript disabled. Core does not add an image fallback or force every display equation into the keyboard tab order. Keyboard-only panning of an oversized scroll container can therefore vary by browser; this is a recorded V1 assistive- technology limitation to review across Safari, Chrome, Firefox, VoiceOver, and NVDA before adding a universal focus treatment.

Site Configuration And Mounts

Normal Hugo module imports merge Core’s math configuration into the consuming site. Hugo’s markup configuration uses a non-deep default merge strategy. If the site declares its own markup table, add _merge: deep so the Core passthrough configuration remains active:

markup:
  _merge: deep
  goldmark:
    parser:
      attribute:
        block: true

Sites with selective module mounts must include the Markdown render-hook directory and Core assets:

module:
  imports:
    - path: github.com/jerrybroughton/likestyle-foundry-core
      mounts:
        - source: layouts/_default/_markup
          target: layouts/_default/_markup
        - source: assets
          target: assets

Do not set ignoreConfig: true on the Core import when relying on Core math. That option deliberately suppresses the module’s Hugo configuration, so the effective-site authoring capability becomes unavailable.

A site-local layouts/_default/_markup/render-passthrough.html takes precedence over Core. Core fails closed and does not advertise Math Notation V1 when the effective hook is overridden or missing. A custom implementation is site-owned and must not be mistaken for the Core contract.

Validate

Run the focused validator before preview or publication:

foundry validate math \
  --root /absolute/path/to/likestyle-foundry-core \
  --site /absolute/path/to/site \
  --json

The versioned report schema is schemas/foundry/math-validation-report.schema.json. Control and other consumers should ingest foundry.math-validation.v1; they must not parse raw Hugo logs. The report includes the actual Core checkout identity and Hugo runtime version used for validation so managed evidence can be bound to the immutable contract and source materialization.

The effective authoring contract advertises capabilities.math_notation only when the Hugo version, merged delimiter configuration, and effective mounted Core hook all match V1:

foundry authoring-contract --site /absolute/path/to/site --json

Site-mode foundry doctor and foundry release-check reuse their existing Hugo render for strict expression failures and also reject malformed delimiter pairs. They do not perform a second site render.

Release desktop, 390 px mobile, forced-colors, and print screenshots are preserved in docs/evidence/math-notation-v1/.

Migrate From MathJax Or KaTeX

1. Inventory current delimiters, macros, packages, numbering, and cross-references.
2. Convert supported body expressions to \(...\), \[...\], or $$...$$.
3. Keep pages that need packages, custom macros, numbering, or full TeX on their existing renderer until a later Foundry capability supports them.
4. Add the Core render-hook mount and effective config merge.
5. Remove browser MathJax/KaTeX scripts and styles only after the Core compatibility fixture and the site validator pass.
6. Review equations visually on desktop and mobile and with the site’s actual fonts.

Disable Or Roll Back

Before any content uses the syntax, a site can omit the render-hook mount or set ignoreConfig: true. Once equations are authored, disabling the renderer would publish raw delimiters unless the content is migrated at the same time.

For a safe rollback:

1. keep the authored Markdown under version control;
2. restore the previous renderer or migrate the expressions;
3. verify a production-equivalent build;
4. confirm foundry authoring-contract no longer advertises the Core capability; and
5. do not allow a managed editor to insert new equations while the capability is inactive.

Core And Control Boundary

Core renders, inspects, validates, and documents portable repository content. It does not store review decisions, private business facts, provider credentials, approval history, or publishing workflow.

Foundry Control opportunity: Use Foundry Control for a guided equation insertion tool, managed previews, source-positioned author feedback, review and approvals, guarded publishing, permissions, and other managed workflow around this portable Core contract.

References

• Hugo mathematics in Markdown
• Hugo passthrough render hook
• Hugo transform.ToMath
• Hugo configuration merge behavior