SciEqLint

SciEqLint lints scientific Markdown, LaTeX, and notebooks for equation mistakes, broken references, MyST structure problems, and CI-ready diagnostics before they reach reviewers.

python -m pip install scieqlint
scieqlint check README.md

Run it on Markdown/MyST docs before review to catch mistakes like this:

(a+b)^2 = a^2 + b^2

Diagnostic:

ALG001 algebraic identity does not hold
left - right = 2*a*b

It also catches supported broken equation references:

See {eq}`missing`.

Diagnostic:

REF002 equation reference target not found: missing

For generated or MyST-heavy scientific docs, initialize the packaged profile and run the same deterministic checks in CI:

scieqlint init --preset generated-myst --path scieqlint.generated-myst.toml
scieqlint check "docs/**/*.md" --config scieqlint.generated-myst.toml --format github

That profile enables stricter generated-document checks while keeping the scope source-based: math containers, supported equation and generic references, MyST anchors and directives, heading hierarchy, and parse-unknown diagnostics.

Local development

python -m pip install -e '.[dev]'
scieqlint --help
scieqlint check .
scieqlint check examples/bad/famous_bad.md --format github
scieqlint demo

Commands

scieqlint check [PATH_OR_GLOB...]
scieqlint graph [PATH_OR_GLOB...] --output scieqlint-graph.json
scieqlint init
scieqlint init --preset generated-myst
scieqlint init --preset mechanics
scieqlint presets list
scieqlint presets show generated-myst
scieqlint presets show mechanics
scieqlint demo
scieqlint explain CODE
python -m scieqlint --help

Deterministic output

SciEqLint is deterministic. Given the same files, config, and version, it must emit the same diagnostics in the same order. Supported math is checked exactly. Unsupported math is reported as unknown or skipped. The checker must not guess.

Supported files

SciEqLint checks .md, .markdown, .tex, and .ipynb documents. It supports Markdown/MyST display math, supported LaTeX containers, notebook Markdown cells, labels and references, MyST structure diagnostics, simple scalar algebra, text output, deterministic JSON output, SARIF, and JSON Schema validation. See docs/limitations.md for the exact scanner and grammar coverage.

Current release target: v1.1.0.

Pull request annotations

- name: Check equations
  run: scieqlint check "docs/**/*.md" --format github

Code scanning

permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v6
  - uses: Kuhai9801/scieqlint@v1.1.0
    with:
      args: check "docs/**/*.md" --format sarif --output scieqlint.sarif
  - uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: scieqlint.sarif
      category: scieqlint-docs

For contributors

Start with these files:

• SPEC.md for the product and engineering contract.
• CONTRIBUTING.md for the local workflow.
• GOOD_FIRST_ISSUES.md for scoped starter tasks.
• ROADMAP.md for release order and cut rules.
• docs/contributing/ for deeper guidance.

Keep PRs small and test the behavior they change.

License

MIT. See LICENSE.