docs.rubocop.org

This repository contains RuboCop’s documentation site. It’s home to both the documentation of RuboCop itself, plus that of its core extensions (the ones maintained by RuboCop’s Core Team).

The site is generated from the AsciiDoc files in the docs folder of RuboCop’s GitHub repo (and the core RuboCop extensions like rubocop-rspec) and is published to https://docs.rubocop.org. Antora is used to convert the manual into HTML. The filesystem layout is described here.

You can find a list of all the documentation modules that are weaved together in the final site in antora-playbook.yml.

To make changes to the manual you simply have to change the files under docs in the relevant repository. The docs will be regenerated manually periodically.

Installing Antora

Note	You’ll have to install node.js before installing Antora.

Installing Antora is super simple:

$ make install

Check out the detailed installation instructions if you run into any problems.

Building the Site

You can build the documentation locally from this repo.

$ cd docs.rubocop.org
$ make build

Tip	You can preview your changes by opening build/site/index.html in your favorite browser.

If you want to make changes to the manual’s page structure you’ll have to edit nav.adoc.

Testing Local Changes

If you’re working on documentation in a local clone of a RuboCop project (e.g., rubocop itself), you can preview your changes without pushing by creating a local playbook that points to your clone:

1. Copy the playbook:

   $ cp antora-playbook.yml antora-playbook-dev.yml

2. In antora-playbook-dev.yml, replace the remote URL with your local path and use HEAD as the branch:

   - url: /path/to/your/local/rubocop
     branches: HEAD
     tags: []
     start_path: docs

   Using branches: HEAD lets Antora pick up uncommitted changes from your worktree.

3. Build with the local playbook:

   $ npm run antora -- antora-playbook-dev.yml

4. Preview the result by opening build/site/index.html in your browser.

Note	antora-playbook-dev.yml is not checked into version control. It’s for local use only.

Deploying to GitHub Pages

Note	You’ll need commit access to the repository for this to work.

The site is automatically deployed to GitHub pages using a GitHub Action. The action will be triggered by any push to the master branch. It can also be triggered manually if needed.

Using Docker

If you prefer not to install Antora on your local machine, you can build the documentation inside a Docker container like this:

$ cd docs.rubocop.org
$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --cache-dir=./.cache/antora antora-playbook.yml

Note that despite the message saying Open file:///antora/build/site/index.html in a browser to view your site., you you should actually look for build/site/index.html in the current directory. (that’s because we’ve mounted the current directory as /antora in the container)

Tip	You can read more about running Antora in a container in the official docs.

Updating the Playbook

When cutting new releases you’ll have to update antora-playbook.yml to add the new tag to the relevant project’s tag list. Here’s how this looks for one of the projects:

- url: https://github.com/rubocop/rubocop-performance.git
  branches: ~
  tags: ['v1.25.0', 'v1.26.1']
  start_path: docs

Tip	You need to add one such block for each new RuboCop module you’re adding to the docs site.

After releases of the main RuboCop gem you also need to update the start_page version in the playbook (e.g., 1.85@rubocop::index.adoc → 1.86@rubocop::index.adoc). This controls where the site root redirects to.

Note	The site only serves tagged releases — no master/main branches. The latest tagged version is automatically published under /latest/ URLs. Contributors can test local changes using a dev playbook (see Testing Local Changes).