Contributing

Openmath is a collection of small HTML source files that are baked into a static site. The source files live in content; the generated site is written to dist.

The project focuses on recursive learning: when a statement uses a previous definition or result, the reader should be able to open that knowledge inline, follow its dependencies backward, and then return to the original statement.

Setup

You need Git, Node.js, and an editor. The build uses the Temml package from npm to convert LaTeX source into MathML.

Fork the Openmath repository, then clone your fork:

git clone YOUR_GIT_URL_HERE
cd openmath
npm install

The repository does not require submodules for normal development.

Building Locally

To bake the source files into the static site, run:

npm run build

To serve the generated site locally, run:

npm run serve

The server serves files from dist.

For active editing, use watch mode. It runs an initial build, watches source files, and rebuilds whenever content, scripts, styles, or data files change:

npm run watch

To watch and serve the site in one command, run:

npm run dev

The development server defaults to http://127.0.0.1:4173/. You can change the host or port with environment variables:

HOST=0.0.0.0 PORT=3000 npm run dev

You can also pass watch options directly to the script:

node scripts/watch.js --serve --host 127.0.0.1 --port 3000 --interval 500

Watch mode ignores dist, node_modules, and .git, so generated files and dependencies do not trigger rebuild loops.

Proof Coverage

The build checks each page's proof quality. A proof block is valid when it contains proof text, the statement body contains at least one knowledge link, and the proof body contains at least one knowledge link. A page's proof quality is the percentage of its proof blocks that are valid. Pages below the threshold are hidden from directory pages and listed on the pages needing proofs worklist.

The default threshold is 50%. To use a different threshold locally, set OPENMATH_PROOF_COVERAGE_THRESHOLD to a number from 0 to 1 before building.

OPENMATH_PROOF_COVERAGE_THRESHOLD=0.8 npm run build

The broader coverage map is seeded by data/coverage_map.json. Add missing disciplines or major results there, and include an href when the result exists in the site.

Improving Existing Pages

Contributions do not have to begin from a blank page. Often a knowledgeable writer can record the shape of an argument before every detail has been expanded. Another contributor can then check the missing step, add the standard result being used, or turn compressed reasoning into a clearer proof.

This kind of decompression is valuable work. If a page contains a true idea but moves too quickly, improving it means making the implicit reasoning explicit enough for the next reader.

Organization

A page that lists other pages is a knowledge directory. A page that contains mathematical content is a knowledge file. Paths should mirror the mathematical organization of the subject.

File and directory names should use lowercase snake_case.

Terminology

• Definition: notation, words, or a named object used to package a larger idea.
• Theorem: an important true statement, usually reused in many places.
• Proposition: a true statement of lesser central importance than a theorem.
• Lemma: a true statement mainly used to prove another result.
• Corollary: a true statement that follows quickly from another result.
• Exercise: something for the reader to try.

Naming IDs

• Use lowercase words separated by hyphens.
• Do not use special symbols in IDs.
• Prefer searchable wording. For example, use "less-than-or-equal-to" instead of symbols.

Content Editing

Source files contain the content that would normally go inside the body of a page. The build wraps them in the shared page template, adds site scripts and styles, and converts LaTeX math into MathML.

Knowledge Directory

Use an index.html file to list pages in a directory:

<fieldset>
  <legend><h1>YOUR TITLE HERE</h1></legend>
  <ul>
    <li><a href="YOUR_FILE_HERE.html">FIRST SECTION</a></li>
    <li><a href="YOUR_FILE_HERE.html">SECOND SECTION</a></li>
  </ul>
</fieldset>

Knowledge File

Definitions and statements should have stable IDs so they can be linked and opened inline.

<div class="definition" id="definition-title">
  <div class="title">Title</div>
  <div class="content">
    Content
  </div>
</div>

Statements With Proofs

Theorems, propositions, lemmas, corollaries, and exercises may include a proof block. Proofs are hidden by default in the generated site.

<div class="theorem" id="theorem-title">
  <div class="title">Title</div>
  <div class="content">
    Statement
  </div>
  <div class="proof">
    Proof
  </div>
</div>

Math

Use \( ... \) for inline math and \[ ... \] for display math.

Let \( n \in \mathbb{N}_1 \).

\[
  n + 1 > n
\]

Inside real math blocks, write LaTeX symbols as LaTeX. For example, use \lt, \gt, \leq, and \geq rather than HTML entities.

Knowledge Links

A knowledge link opens a previous definition or result inline on the current page.

<a class="knowledge-link" href="/number_theory/division.html#definition-divides">divides</a>

Knowledge links can also be used inside LaTeX math. Write the anchor directly inside the math source, and keep the linked text valid LaTeX:

\( <a class="knowledge-link" href="/number_theory/division.html#definition-divides">a \mid b</a> \)

Adding Figures

Prefer scalable vector graphics when possible. Include source files or conversion commands when a figure is generated from another format, so future contributors can edit it.

Submitting Changes

Build the site locally before submitting a pull request:

npm run build

Commit your changes, push them to your fork, and open a pull request. Once the pull request is reviewed and merged, the live site rebuilds from the updated source.