Styling with CSS#

RSM manuscripts are rendered as HTML, which means you can apply CSS classes to any tag using the :class: meta tag. This allows you to customize the appearance of your manuscript without writing custom HTML.

How :class: works#

The :class: meta tag accepts one or more CSS class names (separated by spaces) and applies them to the rendered HTML element. RSM includes built-in CSS classes for common styling needs, and you can also use custom CSS classes if you provide your own stylesheet.

Basic syntax#

:tag: {:class: class-name} content ::

Or for block tags:

:tag: {
  :class: class-name another-class
}

Content here.

::

Built-in CSS classes#

RSM provides several built-in CSS classes you can use immediately.

Font sizes#

RSM includes pre-defined font size classes:

:paragraph: {:class: tiny} Tiny text (0.6rem)

:paragraph: {:class: smallest} Smallest text (0.7rem)

:paragraph: {:class: smaller} Smaller text (0.8rem)

:paragraph: {:class: small} Small text (0.9rem)

:paragraph: {:class: normal} Normal text (1rem)

:paragraph: {:class: large} Large text (1.2rem)

:paragraph: {:class: larger} Larger text (1.4rem)

:paragraph: {:class: largest} Largest text (1.6rem)

:paragraph: {:class: huge} Huge text (2rem)

:paragraph: {:class: huger} Huger text (2.5rem)

These font size classes work on any tag—blocks, inlines, paragraphs, or even math:

Normal equation: $E = mc^2$

Large equation: $ {:class: large} E = mc^2 $

Huge equation: $ {:class: huge} E = mc^2 $

Practical examples#

Emphasizing important theorems#

Combine :class: with multiple classes for custom styling:

:theorem: {
  :title: Main Result
  :class: large
}

This is our central theorem, displayed
in a larger font.

::

Small notes and asides#

Use smaller font sizes for footnotes or side comments:

The main argument proceeds as follows...

:paragraph: {:class: small} Note: This
proof technique was first used by Euler
in 1750.

Multiple classes#

You can apply multiple CSS classes by using braces and separating them with commas:

:span: {:class: {type1, type2}} Styled text ::

:block-tag: {
  :class: {type1, type2}
}
Styled text
::

Using custom CSS#

By default, the rsm CLI utilities will search the current working directory for a css file with the same name as the file you are processing. For example,

$ rsm build manuscript.rsm

Will include manuscript.css if it exists. To use a file with a different name, use the --custom-css flag.

$ rsm build manuscript.rsm --custom-css styles.css

Then in your RSM manuscript, reference your custom classes:

:paragraph: {:class: my-custom-class} Styled content ::

Your CSS file should define the class:

.my-custom-class {
  color: #007acc;
  border-left: 4px solid #007acc;
  padding-left: 1em;
}

Complete example#

Here’s a full example showing custom CSS in action:

## RSM Styling

:span:{:class: highlight-box} This
phrase:: has a custom highlight style
with a colored border and background.

:theorem: {
  :title: Main Theorem
  :class: emphasis-theorem
}
This theorem uses custom styling to
stand out from regular theorems.
::

To create this, you would write the RSM source above and define these CSS classes:

.highlight-box {
  background-color: #fff3cd;
  border-left: 4px solid #ffc107;
}

.emphasis-theorem {
  background-color: #e7f3ff;
  border: 2px solid #0066cc;
  padding: 1.5em;
  border-radius: 8px;
}

Save your RSM source as manuscript.rsm and your CSS as manuscript.css. Build with:

$ rsm build manuscript.rsm

The CSS file will be automatically included since it has the same name as the RSM file.

Best practices#

Warning

Keep styling semantic: Use :class: for presentation only, not content structure or document layout.

Don’t use :class: to fake structural elements like headings, sections, or theorems. If you need a theorem, use :theorem:. If you need a section, use ##. Don’t create a paragraph with custom styling to look like a theorem—that breaks semantic meaning and accessibility.

The :class: meta tag is for how something looks, not what it is.

If you find yourself using :class: to override RSM’s default behavior for semantic tags, please open an issue or contribute to the language. The defaults should work for most cases—if they don’t for you, we want to know.

Use built-in classes first: RSM’s built-in classes handle common cases and work consistently across themes.
Test across themes: If providing custom CSS, test your manuscript in both light and dark themes.
Avoid inline styles: RSM doesn’t support inlined HTML/CSS. Always use CSS classes via :class:.