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. Re-run the build after editing source files, then refresh the browser.

Proof Coverage

The build checks each page's proof coverage. A page's proof coverage is the percentage of its proof blocks that contain content. 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
\]

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>

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.