Information-holographic Unified Field Theory

Documentation for the Information-holographic Unified Field Theory (IHUFT).

Prerequisites

• Python 3.12 or later
• nox (install via pip install nox or your package manager)
• Node.js 18+ with npm (for build-time math rendering)
• Pandoc (for PDF generation)
• A LaTeX distribution such as TeX Live or MiKTeX (for PDF generation via Pandoc)

Why Node.js?

All LaTeX math in the documentation is pre-rendered at build time using KaTeX, so the resulting HTML pages render their equations as static CSS-styled markup with no runtime JavaScript dependency on MathJax. The hooks/math_prerender.py MkDocs hook invokes KaTeX through a small Node script (scripts/render_math.js); the only Node dependency, KaTeX itself, lives in node_tools/ and is installed automatically the first time you build via nox.

The original LaTeX source of every equation is preserved in three places so that readers can copy any equation back out as TeX:

1. inside the rendered MathML, in a standards-compliant <annotation encoding="application/x-tex">…</annotation> element;
2. in a data-latex="…" attribute on the wrapping element; and
3. in a <details><summary>LaTeX source</summary>…</details> disclosure that appears under every display equation (just click "LaTeX source").

Inline math additionally exposes its TeX source as a title="…" hover tooltip.

Getting started

Install nox if you don't have it already:

pip install nox

Two editions: Technical and Layperson

The IHUFT proposal is published in two variants built from the same source markdown:

Edition	Audience	Includes layperson admonitions?
Technical	Scientific community, physicists, mathematicians	No (stripped during build)
Layperson	General educated readers, students, the curious	Yes (preserved during build)

The layperson edition adds plain-language explanatory side-boxes after every technical statement, equation, and concept. They are styled with a distinctive purple border so they are visually separable from the surrounding formal content.

The two editions are produced from one source file by a MkDocs hook (hooks/layperson_filter.py) controlled by the IHUFT_LAYPERSON environment variable. All of the nox sessions below take care of setting this variable correctly for you, but you may also set it yourself if invoking mkdocs directly.

Building

HTML — technical edition (default)

Build the static HTML site without layperson admonitions:

nox -s build

Serve locally with live reload (available at http://127.0.0.1:8000):

nox -s serve

HTML — layperson edition

Build the static HTML site with layperson admonitions included:

nox -s build-html-layperson

Serve the layperson edition locally with live reload:

nox -s serve-layperson

PDF — technical edition (default)

Generate the technical PDF with Pandoc and LaTeX:

nox -s build-pdf

PDF — layperson edition

Generate the layperson PDF with Pandoc and LaTeX:

nox -s build-pdf-layperson

PDFs are written to build/pdf/ as ihuft.pdf (technical) and ihuft-layperson.pdf (layperson). Math is rendered natively by LaTeX, so a working LaTeX installation (including lualatex) is required.

All targets

Session	Edition	Description
nox -s build	Technical	Alias for build-html; build the HTML site
nox -s build-html	Technical	Build the MkDocs HTML site
nox -s build-html-layperson	Layperson	Build the MkDocs HTML site with plain-language sections
nox -s build-pdf	Technical	Generate PDF via Pandoc + LuaLaTeX
nox -s build-pdf-layperson	Layperson	Generate PDF with plain-language sections
nox -s serve	Technical	Serve locally with live reload
nox -s serve-layperson	Layperson	Serve layperson edition with live reload
nox -s install-katex	—	Install/refresh KaTeX into node_tools/ (auto-run)
nox -s all	Technical	Build both HTML and PDF (technical)
nox -s all-layperson	Layperson	Build both HTML and PDF (layperson)
nox -s clean	—	Remove all build artifacts

Note: All HTML build and serve sessions automatically run install-katex if node_tools/node_modules/katex/ is missing. PDF builds do not need KaTeX (LaTeX itself handles math natively for PDF output), so those sessions skip the check.

Manual control via the environment variable

If you want to invoke mkdocs directly instead of through nox, set the IHUFT_LAYPERSON environment variable. The hook accepts any of 1, true, yes, or on (case-insensitive) to enable the layperson edition; anything else (including an unset variable) selects the technical edition.

# Technical edition (default)
mkdocs build
mkdocs serve

# Layperson edition
IHUFT_LAYPERSON=1     mkdocs build
IHUFT_LAYPERSON=true  mkdocs serve
IHUFT_LAYPERSON=yes   mkdocs build

The same variable works for the serve command, so you can preview either edition locally without rebuilding from a different source tree.

Writing layperson admonitions

When editing the proposal, add a layperson explanation using the !!! layperson admonition syntax (an optional title is supported):

!!! layperson "What this means in plain words"
    Several sentences of plain-language explanation appropriate for a
    non-specialist reader.  Indent every line by four spaces, exactly as for
    any other Material-for-MkDocs admonition.

    Blank lines are allowed within the block and will be preserved.

These blocks are automatically stripped from the technical edition and preserved in the layperson edition. Use them liberally: they exist so that the same source file can serve both audiences without duplicating content.

Contributing

See CONTRIBUTING.md.

License

MIT