rsm-markup 0.4.0

ReStructured Manuscripts (RSM) markup language

Readable Science Markup (RSM)

The web-first authoring software for scientific manuscripts.

RSM is a suite of tools that aims to change the way scientific manuscripts are published and shared using modern web technology. Currently, most scientific publications are made with LaTeX and published in PDF format. While the capabilities of LaTeX and related software are undeniable, there are many pitfalls. RSM aims to cover this gap by allowing authors to create web-first manuscripts that enjoy the benefits of the modern web.

One of the main aims of the RSM suite is to provide scientists with tools to author scientific manuscripts in a format that is web-ready in a transparent, native way that is both easy to use and easy to learn. In particular, RSM is a suite of tools that allow the user to write a plain text file (in a special .rsm format) and convert the file into a web page (i.e. a set of .html, .css, and .js files). These files can then be opened natively by any web browser on any device.

• Learn more in the official website.
• Try it out in the online editor.
• Get started with the docs.

Contributing

This project is under constant development and contributions are very much welcome! Please develop your feature or fix in a branch and submit a PR.

Rebuilding the Standalone JS Bundle

The file rsm/static/rsm-standalone.js is a pre-built bundle of all RSM JavaScript for standalone HTML files (files that can be opened directly from file:// URLs).

If you modify any JS files in rsm/static/, you must regenerate this bundle:

npx esbuild rsm/static/onload.js --bundle --format=iife --global-name=RSM --outfile=rsm/static/rsm-standalone.js

This bundles onload.js and all its dependencies into a single IIFE that exposes RSM.onload() and RSM.onrender(). The bundle is committed to the repo so there's no runtime dependency on esbuild.

Development Setup

Prerequisites

• Python 3.10 or higher
• uv - Fast Python package installer
• just - Command runner

Installation

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

Install just

# macOS
brew install just

# Linux
cargo install just

# Windows
scoop install just

Clone and install rsm-markup

git clone --recurse-submodules https://github.com/leotrs/rsm.git
cd rsm
just install

This installs:

• rsm-markup in editable mode (you can modify the code)
• tree-sitter-rsm from PyPI as a pre-built wheel (compiled grammar)
• All development and documentation dependencies

Note: The tree-sitter-rsm grammar is installed from PyPI with platform-specific pre-built binaries. You don't need to build anything unless you're modifying the grammar itself.

Common Tasks

just                  # List all available commands
just test             # Run fast tests
just test-all         # Run all tests including slow ones
just lint             # Format code and run linter
just check            # Run lint + tests (quality gate)
just docs-serve       # Serve docs with live reload

Grammar Development

Most developers don't need this. Only use these steps if you're modifying the tree-sitter grammar in tree-sitter-rsm/grammar.js.

# Install tree-sitter-rsm in editable mode (overrides PyPI version)
just install-local

# After modifying grammar.js in tree-sitter-rsm/
just build-grammar

The difference between just install and just install-local:

Command	tree-sitter-rsm source	Editable?	Use when
just install	PyPI wheel	No	Developing rsm-markup code (most common)
just install-local	Local submodule	Yes	Modifying the grammar itself

Publishing

This project uses uv for dependency management and just for task automation.

To release a new version to PyPI:

1. Update version in pyproject.toml
2. Create a git tag: git tag v0.3.3 && git push origin v0.3.3
3. Publish: just publish

Or use the GitHub Actions workflow by creating a release on GitHub.