cRSTLint

Copyleft (C) 2026 Rénich Bon Ćirić

An RST linter implementation built on the crst Crystal shard.

cRSTLint is a command-line tool and Crystal library that provides comprehensive linting capabilities for reStructuredText (RST) documents. It is built as an implementation of the crst parser shard, which provides the core RST parsing functionality.

Features

• RST syntax validation
• Document structure checking
• Unknown directive detection
• Reference validation
• Auto-fix capability for common issues (e.g., trailing whitespace)
• Multiple output formats (human-readable, JSON)

Requirements

Depending on your installation method, ensure the following minimal requirements are met:

Runtime Requirements (Pre-built Binary)

• Linux AMD64 system

Build Requirements (Compiling from Source)

• Crystal Compiler: v1.20.0 or greater
• Shards: Crystal package manager (bundled with Crystal)
• GNU Make & Git
• Standard Build Essentials (gcc, g++, libevent-devel, pcre2-devel, gc-devel)

Installation

Fast-Track (Pre-built Binary)

Get up and running instantly by fetching the compiled static binary directly from the GitLab API (no dependencies or compilation required).

mkdir -p ~/.local/bin
curl -L -o ~/.local/bin/crstlint "https://gitlab.com/api/v4/projects/renich%2Fcrstlint/jobs/artifacts/v0.8.4/raw/bin/crstlint?job=release"
chmod +x ~/.local/bin/crstlint

[!NOTE] Make sure ~/.local/bin is present in your $PATH environment variable.

From Source

Clone and compile the source directly. We recommend placing the repository source code in ~/src/crstlint/:

# 1. Clone the repository to the recommended src directory
git clone https://gitlab.com/renich/crstlint.git ~/src/crstlint
cd ~/src/crstlint

# 2. Build and install locally to ~/.local/bin
make install-local

Package Managers & Distro Integration

cRSTLint is designed to be fully compatible with GNU/Linux distribution packaging guidelines (FHS and Autotools-style conventions). The repository GNUmakefile supports standard lowercase directory overrides and staging prepends:

# Example: Packaging or installing system-wide to /usr/bin
make
sudo make install prefix=/usr DESTDIR=/path/to/packaging/root

Supported installation variables include:

• prefix: Target directory prefix (defaults to /usr/local).
• bindir: Binary installation directory (defaults to $(prefix)/bin).
• DESTDIR: Staging directory for package managers (prepended to all paths).
• Legacy uppercase wrappers (PREFIX and BINDIR) are fully supported for backwards compatibility.

Usage

Check a single file:

crstlint document.rst

Recursively check a directory:

crstlint --recursive docs/

Automatically fix issues:

crstlint --fix document.rst

JSON output:

crstlint --format json document.rst

Configuration

cRSTLint can be configured using a .crstlintrc.yaml file in your project root. See the included .crstlintrc.yaml for all options.

Development

git config core.hooksPath .githooks  # Enable Git hooks
make deps    # Install dependencies
make test    # Run tests
make lint    # Run linting
make build   # Build binary
make setup   # Full development setup

For detailed architecture documentation, see docs/technical/architecture.rst.

Contributing

Please read CONTRIBUTING.rst for details on our code of conduct, and the process for submitting pull requests.

Credits

• Co-developed with ❤️ by Gemini AI renich+gemini@woralelandia.com

🛡️ Code of Honor

This project adheres to the Universal Code of Honor. By participating, you are expected to uphold this code.

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.