ManuscriptLint 🐈‍⬛📝

ESLint for academic manuscripts.

ManuscriptLint is an open-source preflight linter for academic manuscripts. It checks a LaTeX project before submission and catches structural problems that are easy to miss during writing.

Part of 喵造实验室 / MeowBuild Lab and the Academic Lint family:

• FigureLint — figure QA
• RefLint — reference QA
• ManuscriptLint — manuscript preflight

Current checks

• duplicate LaTeX labels
• unresolved \\ref{} / \\eqref{} references
• citations missing from BibTeX libraries
• missing \\input{} / \\include{} source files
• missing \\includegraphics{} files
• figure / table environments without captions
• TODO / FIXME markers left in reachable manuscript text
• entry-point-aware LaTeX include graph
• include-cycle detection
• unused figure files in conventional figure directories (informational)
• unused BibTeX entries (informational, respects \\nocite{*})
• optional FigureLint and RefLint integration
• JSON output for editor / CI integrations
• native GitHub Actions annotations
• reusable GitHub composite action
• CI-friendly exit codes and strict mode

When a project directory contains a clear \\documentclass{} entry point, ManuscriptLint follows its \\input{}, \\include{}, and \\subfile{} graph. Unrelated draft .tex files are not treated as active manuscript content.

Install

Requires Python 3.10+.

The first public release is prepared for PyPI. After v0.1.0 is published:

pip install manuscriptlint

From source

git clone https://github.com/coocoomaomao/ManuscriptLint.git
cd ManuscriptLint
python -m venv .venv
pip install -e .

For development:

pip install -e ".[dev]"
pytest

Usage

Check one manuscript:

manuscriptlint check paper.tex

Check a whole LaTeX project:

manuscriptlint check paper/

Treat warnings as CI failures:

manuscriptlint check paper/ --strict

Machine-readable JSON:

manuscriptlint check paper/ --format json

Emit native GitHub workflow annotations:

manuscriptlint check paper/ --github-annotations

Run the wider Academic Lint toolchain when FigureLint / RefLint are installed:

manuscriptlint check paper/ --figurelint --reflint

GitHub Actions

Before the first tag is published, use @main:

- uses: coocoomaomao/ManuscriptLint@main
  with:
    path: paper/
    strict: "true"

After v0.1.0, pin the Action to @v0.1.0.

See GitHub Action usage.

Philosophy

ManuscriptLint focuses on deterministic preflight checks. It should identify verifiable structural problems without pretending to judge scientific quality, novelty, or whether a paper will be accepted.

Unused figures and unused references are currently informational because research repositories often keep intentional extras.

Release

The first public release is v0.1.0.

• v0.1.0 release notes
• Publishing guide

Planned next

• graphicspath / macro handling improvements
• supplementary-material checks
• source-backed publisher presets
• DOCX manuscript support

License

MIT