Guide

SuperSlim reads the Slim 5 grammar and renders the HTML Slim renders. Installing it is swapping a gem; this page covers the rest.

Rails
Plain Ruby
Options
Tailwind class names
Embedded engines
Migrating from Slim
What SuperSlim leaves out

Rails

# Gemfile
gem "super-slim" # instead of slim-rails

A railtie registers the .slim handler with Action View. Nothing else to configure:

output is escaped with Rails’ html_safe rules, and == outputs raw;
templates whose format is XML (.xml, .rss, .atom) render as XML, with <link /> and doctype xml;
annotate_rendered_view_with_filenames adds its BEGIN/END comments, and streaming works;
every - and = line compiles onto its template line, so an exception’s backtrace points at the right line — including after a ruby: block or a multi-line attribute list, where Slim drifts;
/# locals: (post:) declares a partial’s strict locals.

Plain Ruby

require "super_slim"

code = SuperSlim.compile(source, file: "page.slim")
# Ruby that builds the HTML in _buf and returns it

Options

One setting applies everywhere, typically in config/initializers/super_slim.rb:

Setting	Default	Effect
`SuperSlim.tailwind_classes = true`	off	Let class shortcuts read Tailwind class names. Tailwind

It can be overridden per compile, alongside the options of SuperSlim.compile:

Option	Default	Effect
`file:`	`nil`	The path shown in syntax errors and backtraces.
`format:`	`:html`	`:xml` closes void tags (`<br />`) and allows `doctype xml`.
`html_safe:`	when `String#html_safe?` exists	Leave `html_safe` strings unescaped, the way Rails expects.
`tailwind_classes:`	`SuperSlim.tailwind_classes`	Tailwind class names for this template.

Tailwind class names

Slim cuts .rounded-b-[3px] at the bracket, renders .size-2.5 as class="size-2 5", and refuses .lg:[&:nth-child(3)]:hover:underline. Turn on tailwind_classes and the . shortcut takes any Tailwind class name:

Template

.p-1.rounded-b-[3px].lg:[&:nth-child(3)]:hover:underline
.font-['Open_Sans'].bg-(--brand).mx-0.5.w-1/2.!font-bold
ul.*:p-2

config/initializers/super_slim.rb, and .super-slim.yml for the CLI

SuperSlim.tailwind_classes = true

tailwind_classes: true

Attribute lists keep their meaning: Tailwind never puts a bracket right after a letter or a digit, so a.btn[href="/"] is still a link with a class and an href. A colon followed by a space still nests a tag (li.item: a), and a final / still closes one.

Checked on 7,505 templates from 31 apps: 16 compile differently with the option, every one of them a Tailwind class Slim breaks. It stays off by default all the same, so that switching from Slim changes no template. It only changes how templates are read: the compiled Ruby, so the render time, is the same.

Embedded engines

ruby:, javascript:, css: and markdown: work as in Slim, interpolation included. markdown: renders through Markly: add gem "markly" to use it. SuperSlim itself depends on no gem.

Migrating from Slim

Slim defaults to format: :xhtml and sort_attrs: true. If you never changed them, first switch Slim to format: :html, sort_attrs: false and run your test suite: that is the HTML SuperSlim renders.
Replace slim-rails (or slim) with gem "super-slim".
Remove any Slim::Engine.set_options or with_options call. Custom shortcuts are gone: write the attribute instead.
Run super-slim format once and review the diff, then add super-slim lint and super-slim format --check to CI.

What SuperSlim leaves out

Each fails at compile time with a clear error instead of being silently ignored:

the XHTML format, sort_attrs, attr_quote, pretty, js_wrapper and every Temple option;
the coffee:, sass:, scss:, less:, erb:, builder:, textile:, rdoc:, asciidoc: and wiki engines, and /[if IE] conditional comments;
the logic_less, translator, include and smart plugins, and custom shortcuts (only #id and .class).

They can come back if people ask, as long as they cost nothing at render time.