Using rumdl to Maintain Markdown Documents

Table of Contents

Markdown has effectively become the standard for formatted text. Many, many products now use Markdown, from Jupyter notebooks for interactive computation to static Website generators like Hugo and Zensical. Current versions of the LibreOffice office suite support Markdown. LLMs now use Markdown as their standard text format for input and output.

The Markdown format supports extensions and embedded elements. You can embed metadata (frontmatter), MDX components and Mermaid diagrams into Markdown documents, as well as links to assets like images.

Markdown files often contain formatting errors and broken links. This means that we should always check the Markdown documents that we rely on.

The rumdl tool provides both formatting and linting for Markdown documents. You can run rumdl with Git hooks, on-demand by using a hook manager, and as part of continuous integration pipelines. It supports the popular variations of Markdown, such as CommonMark, GFM and Python Markdown.

The rumdl checks test relative links and anchor links. You will need to use a tool like lychee to check the links to external sites.

Installing `rumdl` #

To install rumdl on a development system, use the packages from the npm or Python registries. If you use a package management tool like npm, pipx, or uv, you can specify which version of rumdl it installs:

npm install -g rumdl@0.2.36

pipx install rumdl==0.2.36

You can also install rumdl with Homebrew. Homebrew always installs the latest version of rumdl:

brew install rumdl

Example Configuration File for `rumdl` #

This example configuration file for a project enable the complete set of features that rumdl provides, including reflow of text:

# rumdl configuration file
#
# https://rumdl.dev/

[global]

enable = ["ALL"]

exclude = [
    ".git",
    "LICENSES",
    "LICENSE.md"
]

line-length = 120

respect-gitignore = true

[MD004]
style = "dash"

[MD013]
reflow = true
reflow-mode = "normalize"

Using `rumdl` in Your Editor #

Set up integrations with your text editors to automatically receive feedback as you work and enable the editor to format Markdown documents with rumdl.

Enabling Visual Studio Code Integration #

To use rumdl with Visual Studio Code or a compatible editor, install the rvben.rumdl extension.

The extension includes a copy of rumdl. This means that it will function even if you have not installed a package for rumdl.

Enabling Integration with JetBrains IDEs #

To enable support for rumdl in JetBrains IDEs such as PyCharm, install the rumdl plugin.

Automating Checks with `prek` or `pre-commit` #

To automate the maintenance of Markdown files in your project, add Git hooks. The most popular tools for managing hooks are prek and pre-commit. The prek tool supersedes pre-commit. It can use hooks that are written for pre-commit, and works with existing pre-commit project configurations.

This example .pre-commit-config.yaml configuration file for a project uses the copy of rumdl on the system:

---
minimum_prek_version: "0.4.0"

repos:
  - repo: builtin
    hooks:
      - id: check-added-large-files
      - id: check-case-conflict
      - id: check-json
      - id: check-merge-conflict
      - id: check-symlinks
      - id: check-toml
      - id: check-vcs-permalinks
      - id: check-xml
      - id: check-yaml
      - id: destroyed-symlinks
      - id: end-of-file-fixer
      - id: fix-byte-order-marker
      - id: mixed-line-ending
      - id: trailing-whitespace

  - repo: local
    hooks:

      - id: rumdl-fmt
        name: rumdl fmt
        description: Format Markdown files in place. Always exits 0; relies on pre-commit file-change detection.
        entry: rumdl fmt
        language: system
        types: [markdown]
        require_serial: true

      - id: rumdl-check
        name: rumdl check
        description: Lint Markdown files. Exits 1 if violations are found. Run rumdl-fix to auto-fix in place.
        entry: rumdl check
        language: system
        types: [markdown]
        require_serial: true

      - id: rumdl-fix
        name: rumdl fix
        description: Fix Markdown files.
        entry: rumdl check --fix
        language: system
        types: [markdown]
        require_serial: true
        stages: [manual]

The hooks automatically run on the staged changes each time that you commit. The only exception is rumdl-fix, which is manual and runs when explicitly called.

To run a tool without commiting a change, use prek run. If you add the option --all-files it will check the current files in the project, not just staged changes. For example, to run the rumdl-fix hook on the project, use this command:

prek run rumdl-fix --all-files

To run every hook on the project, use this command:

prek run --all-files

Installing rumdl #

Example Configuration File for rumdl #

Using rumdl in Your Editor #