Guidedog / Documentation 0.2.0

Mathematics and proofs¶

An equation is useful when it makes a relation easier to inspect. Define every symbol before relying on it. State the units where they matter. The equation should support the explanation, not replace it.

Inline and display mathematics¶

Use the math role for a short expression. Use the math directive for a display. Write the common LaTeX mathematics subset that both targets understand.

A side of length :math:`s` encloses area :math:`s^2`.

.. math::
   :label: area-square

   A = s^2

The relation is :eq:`area-square`.

A side of length \(s\) encloses area \(s^2\).

(1)¶\[A = s^2\]

The relation is (1). Guidedog gives a labelled equation a stable target. The HTML builder supplies MathJax markup. The PDF renderer translates the supported LaTeX subset to Typst mathematics. An unsupported PDF command is reported. Arbitrary LaTeX packages are not evaluated.

A small proof¶

Let \(U\) be the bytes already charged to a budget. Let \(B\) be its limit. Let \(n\) be a requested allocation. Assume all three values are nonnegative and \(U \le B\).

Admission rule. Admit the request exactly when

(2)¶\[n \le B - U.\]

Claim. An admitted request preserves \(U + n \le B\).

Proof. Add \(U\) to both sides of (2). The result is \(U+n \le B\). The implementation tests the subtraction form. It does not first compute \(U+n\), which could overflow a machine integer. The proof and the arithmetic order agree.

Boundary. This accounts for charged host storage. It does not bound the separate Typst compiler’s internal allocations. A proof is only as strong as the boundary it states.

HTML setup¶

These projects bundle MathJax 3.2.2 with its SVG font data. The bundle is loaded only on pages containing mathematics. It makes these pages readable offline after a build. No diagram script or web font service is required.

For your own project, the default uses MathJax from a CDN. To serve a local copy, place it in _static and set:

html_static_path = ["_static"]
mathjax_path = "_static/tex-svg-full.js"

JavaScript is needed here to typeset web equations. Without it, their source remains visible. PDF equations do not need browser JavaScript. See the MathJax component contract.