Your first manuscript#

Create a new file called manuscript.rsm and add the following contents

## Introduction
Web-first scientific publishing.

In the command line, cd to the directory where the manuscript.rsm file is stored and execute

$ rsm build manuscript.rsm

This will create a new file called manuscript.html in the same directory. Use rsm serve to open this file with your web browser to see the output created by RSM.

RSM provides a linter as a command line utility. Run the following command to see what the linter suggests.

$ rsm check manuscript.rsm
src:1:12: LINT: Manuscript with no title

Here, the linter is telling us that our manuscript is missing a title. We can rectify that by editing manuscript.rsm as follows

# Readable Science Markup

## Introduction
Web-first scientific publishing.

Run again the rsm check command, and the warning should have disappeared. You can now run rsm build again and refresh your browser to see now the title of your manuscript displayed.

Tip

rsm serve will automatically rebuild the html file and refresh your browser when it detects changes in the source file.

Troubleshooting#

Common issues when getting started with RSM:

Build errors#

“Command not found: rsm”

  • Solution: Make sure RSM is installed: pip install rsm-lang

  • Check installation: rsm --version

  • If using a virtual environment, ensure it’s activated

“Error: Could not find file manuscript.rsm”

  • Solution: Use cd to navigate to the directory containing your .rsm file

  • Or provide the full path: rsm build /path/to/manuscript.rsm

“SyntaxError: unexpected tag at line X”

  • Solution: Run rsm check manuscript.rsm to see detailed error messages

  • Common causes: - Missing closing Halmos :: - Misspelled tag name (e.g. :section instead of :section:) - Incorrect meta tag syntax (check braces and colons)

Linter warnings#

“LINT: Manuscript with no title”

  • Not an error, but good practice to add a title

  • Add at the top of your file: # Your Title Here

“LINT: Missing closing Halmos”

  • Every opening tag needs a closing ::

  • Example: :section: content :: not :section: content

  • Use proper indentation to track nested tags

Browser issues#

“Manuscript doesn’t render correctly in browser”

  • Try a hard refresh: Ctrl+Shift+R (Linux/Windows) or Cmd+Shift+R (Mac)

  • Check browser console (F12) for JavaScript errors

  • Verify static/ folder is in same directory as index.html

“Math equations don’t display”

  • RSM uses MathJax for math rendering (loads from CDN)

  • Check your internet connection

  • Or serve locally: rsm build manuscript.rsm --serve (includes local MathJax)

Still stuck?#

  • Check existing GitHub issues: aris-pub/rsm#issues

  • Open a new issue with: - Your RSM version (rsm --version) - Minimal example that reproduces the problem - Full error message