Slim-Lint

slim-lint is a tool to help keep your Slim files
clean and readable. In addition to style and lint checks, it integrates with
RuboCop to bring its powerful static
analysis tools to your Slim templates.

You can run slim-lint manually from the command line, or integrate it into
your SCM hooks.

• Requirements
• Installation
• Usage
• Configuration
• Linters
• Editor Integration
• Git Integration
• GitHub Integration
• Rake Integration
• Contributing
• Changelog
• License

Requirements

• Ruby 3.0+
• Slim 3.0+

Installation

gem install slim_lint

Usage

Run slim-lint from the command line by passing in a directory (or multiple
directories) to recursively scan:

slim-lint app/views/

You can also specify a list of files explicitly:

slim-lint app/**/*.slim

slim-lint will output any problems with your Slim, including the offending
filename and line number.

Configuration

slim-lint will automatically recognize and load any file with the name
.slim-lint.yml as a configuration file. It loads the configuration based on
the directory slim-lint is being run from, ascending until a configuration
file is found. Any configuration loaded is automatically merged with the
default configuration (see config/default.yml).

Here's an example configuration file:

exclude:
  - 'exclude/files/in/this/directory/from/all/linters/**/*.slim'

linters:
  EmptyControlStatement:
    exclude:
      - 'app/views/directory_of_files_to_exclude/**/*.slim'
      - 'specific/file/to/exclude.slim'

  LineLength:
    include: 'specific/directory/to/include/**/*.slim'
    max: 100

  RedundantDiv:
    enabled: false

All linters have an enabled option which can be true or false, which
controls whether the linter is run, along with linter-specific options. The
defaults are defined in config/default.yml.

Linter Options

Global File Exclusion

The exclude global configuration option allows you to specify a list of files
or glob patterns to exclude from all linters. This is useful for ignoring
third-party code that you don't maintain or care to lint. You can specify a
single string or a list of strings for this option.

Skipping Frontmatter

Some static blog generators such as Jekyll include
leading frontmatter to the template for their own tracking purposes.
slim-lint allows you to ignore these headers by specifying the
skip_frontmatter option in your .slim-lint.yml configuration:

skip_frontmatter: true

Disabling Linters For Specific Code

Slim-lint linters

To disable a slim-lint linter, you can use a slim comment:

/ slim-lint:disable TagCase
IMG src="images/cat.gif"
/ slim-lint:enable TagCase

Rubocop cops

To disable Rubocop cop, you can use a comment control statement:

- # rubocop:disable Rails/OutputSafety
p = raw(@blog.content)
- # rubocop:enable Rails/OutputSafety

Linters

You can find detailed documentation on all supported linters by following the
link below:

» Linters Documentation

Editor Integration

Sublime Text

Install the
Sublime slim-lint plugin.

Emacs

If you use Flycheck, support for slim-lint is included as of version
20160718.215 installed from MELPA.

Atom

Install the linter-slim-lint
plugin by running apm install linter-slim-lint.

Visual Studio Code

Install the
VS Code slim-lint plugin.

Git Integration

If you'd like to integrate slim-lint into your Git workflow, check out
overcommit, a powerful and flexible
Git hook manager.

Github Integration

To run slim-lint in your GitHub Actions CI pipeline,
use the github reporter, for example:

on:
  pull_request:
  push:
    branches: [ main ]

jobs:
  lint:
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: .ruby-version
          bundler-cache: true

      - name: Lint Slim templates for consistent style
        run: bundle exec slim-lint -r github app/views

On lint failures, this setup will create annotations in your pull requests on GitHub.

Rake Integration

To execute slim-lint via a Rake task, make
sure you have rake included in your gem path (e.g. via Gemfile), and add
the following to your Rakefile:

require 'slim_lint/rake_task'

SlimLint::RakeTask.new

By default, when you execute rake slim_lint, the above configuration is
equivalent to running slim-lint ., which will lint all .slim files in the
current directory and its descendants.

You can customize your task by writing:

require 'slim_lint/rake_task'

SlimLint::RakeTask.new do |t|
  t.config = 'custom/config.yml'
  t.files = ['app/views', 'custom/*.slim']
  t.quiet = true # Don't display output from slim-lint to STDOUT
end

You can also use this custom configuration with a set of files specified via
the command line:

# Single quotes prevent shell glob expansion
rake 'slim_lint[app/views, custom/*.slim]'

Files specified in this manner take precedence over the task's files
attribute.

Contributing

We love getting feedback with or without pull requests. If you do add a new
feature, please add tests so that we can avoid breaking it in the future.

Speaking of tests, we use rspec, which can be run by executing the following
from the root directory of the repository:

bundle exec rspec

Changelog

If you're interested in seeing the changes and bug fixes between each version
of slim-lint, read the Slim-Lint Changelog.

License

This project is released under the MIT license.