rumdl

https://rumdl.dev/
Admin
rumdl is a fast Markdown linter and formatter written in Rust that provides multi-flavor support,...
Tokens:235,351
Snippets:2,863
Trust Score:5.3
Update:3 days ago
Show doc for...
Tokens:
Raw
### rumdl vscode command examples

Source: https://rumdl.dev/usage/cli

Shows how to install the VS Code extension, check installation status, update the extension, or force reinstall.

```bash
rumdl vscode                     # Install extension
rumdl vscode --status            # Check installation
rumdl vscode --update            # Update the installed extension
rumdl vscode --force             # Force reinstall
```

--------------------------------

### Correct npm install command with output

Source: https://rumdl.dev/md014

An example of a shell command that correctly includes its expected output.

```shell
$ npm install
added 125 packages, and audited 126 packages in 3s

14 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
```

--------------------------------

### Start LSP Server and Install VS Code Extension

Source: https://rumdl.dev/markdownlint-comparison

Commands to start the built-in Language Server Protocol server with 'rumdl server' and install the VS Code extension with 'rumdl vscode'. These enable real-time linting, quick fixes, and hover documentation.

```bash
# Start LSP server
rumdl server

# Install VS Code extension
rumdl vscode

```

--------------------------------

### Neovim nvim-lspconfig Setup

Source: https://rumdl.dev/usage/editors

Setup using the nvim-lspconfig plugin.

```lua
require('lspconfig').rumdl.setup{}
```

--------------------------------

### rumdl server command example

Source: https://rumdl.dev/usage/cli

Starts the Language Server Protocol (LSP) server.

```bash
rumdl server                     # Start Language Server Protocol server
```

--------------------------------

### Example output for configuration search

Source: https://rumdl.dev/configuration

This output demonstrates how rumdl reports the start directory, ignored HOME paths, resolved home directory, and the selected user configuration file.

```text
start directory: C:\Users\me\project
ignored HOME="/c/Users/me": it is an MSYS-style path (/c/Users/...), not a native Windows path
home directory: C:\Users\me (from USERPROFILE or the user profile API)
...
selected user config: C:\Users\me\.config\rumdl\rumdl.toml
```

--------------------------------

### Install pre-commit hooks

Source: https://rumdl.dev/usage/pre-commit

Run this command to install the configured hooks.

```bash
pre-commit install
```

--------------------------------

### Correct Project README Heading Example

Source: https://rumdl.dev/md041

A valid project README starting with a top-level Markdown heading.

```markdown
# Project README

This project provides tools for...
```

--------------------------------

### Install with uv

Source: https://rumdl.dev/getting-started/installation

Install rumdl as a tool or run it without installation using uv.

```bash
# Install as a tool
uv tool install rumdl

# Or run without installing
uvx rumdl check .
```

--------------------------------

### MD043 Configuration Example

Source: https://rumdl.dev/md043

Example configuration for MD043 defining the required heading sequence.

```ini
[MD043]
headings = ["# Overview", "## Installation", "## Usage", "## License"]
```

--------------------------------

### Example Lists

Source: https://rumdl.dev/flavors/pandoc

Create numbered examples that can be referenced later in the document.

```markdown
(@) The first example.
(@good) The second example.
(@) The third example.

As shown in (@good), this approach works.

```

--------------------------------

### MD076 configuration example

Source: https://rumdl.dev/md076

Example configuration for the MD076 rule.

```toml
[MD076]
style = "consistent"              # "consistent" (default), "loose", or "tight"
allow-loose-continuation = false  # allow blank lines around continuation paragraphs
```

--------------------------------

### Allow-list configuration example

Source: https://rumdl.dev/md084

Example of adding specific Unicode codepoints to the allow-list.

```toml
[MD084]
allow = ["U+200B", "U+2060"]
```

--------------------------------

### Install mdformat

Source: https://rumdl.dev/mdformat-comparison

Installation commands for mdformat and its plugins.

```bash
pip install mdformat
# With plugins:
pip install mdformat-gfm mdformat-frontmatter
```

--------------------------------

### Install mdformat plugins

Source: https://rumdl.dev/mdformat-comparison

Use pip to install plugins for GFM and frontmatter support in mdformat.

```bash
pip install mdformat-gfm mdformat-frontmatter
```

--------------------------------

### Neovim Manual LSP Setup (pre-0.11)

Source: https://rumdl.dev/usage/editors

Fallback configuration for Neovim versions older than 0.11 using vim.lsp.start.

```lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "markdown",
  callback = function()
    vim.lsp.start({
      name = "rumdl",
      cmd = { "rumdl", "server" },
      root_dir = vim.fs.dirname(vim.fs.find({".rumdl.toml", ".git"}, { upward = true })[1]),
    })
  end,
})
```

--------------------------------

### MagicLink example

Source: https://rumdl.dev/md018

Example content where MagicLink references are used at the start of lines.

```markdown
# PRs that are helpful for context

#10 discusses the philosophy behind the project, and #37 shows a good example.

#Summary

```

--------------------------------

### Incorrect Document Start Example 1

Source: https://rumdl.dev/md041

An invalid document that starts with text instead of a top-level heading.

```markdown
Welcome to our documentation! This guide will help you...

## Installation

First, install the dependencies...
```

--------------------------------

### Example mkdocs.yml configuration

Source: https://rumdl.dev/md074

A sample mkdocs.yml file structure demonstrating valid navigation entries.

```yaml
site_name: My Docs
docs_dir: docs
nav:
  - Home: index.md
  - Guide: guide.md
  - API:
    - Overview: api/overview.md
    - Reference: api/reference.md

```

--------------------------------

### Enable opt-in rules alongside defaults

Source: https://rumdl.dev/global-settings

Example showing how to add specific opt-in rules like table formatting and frontmatter key sort.

```toml
[global]
extend-enable = ["MD060", "MD072"]  # Add table formatting and frontmatter key sort
```

--------------------------------

### Incorrect heading usage example

Source: https://rumdl.dev/md024

An example of a document structure that violates the MD024 rule due to duplicate 'Setup' headings.

```markdown
# Project Setup

## Setup

Details about npm install...

## Setup

Details about environment setup...

## Setup

How to run the test suite...
```

--------------------------------

### Initialize configuration file

Source: https://rumdl.dev/getting-started/quickstart

Create a default .rumdl.toml file or one based on a specific preset.

```bash
# Create .rumdl.toml with defaults
rumdl init

# Create with specific preset
rumdl init --preset google
```

--------------------------------

### rumdl init usage examples

Source: https://rumdl.dev/usage/cli

Shows basic usage of the init command: creating a default .rumdl.toml, using the google preset, and specifying a custom output path.

```bash
rumdl init                       # Create .rumdl.toml
rumdl init --preset google       # Use Google style preset
rumdl init --output custom.toml  # Custom output path

```

--------------------------------

### Incorrect npm install command

Source: https://rumdl.dev/md014

An example of a shell command that is missing its expected output.

```shell
$ npm install
```

--------------------------------

### Fixed Document Example

Source: https://rumdl.dev/md041

The corrected version of an invalid document, now starting with a top-level heading.

```markdown
# Documentation

Welcome to our documentation! This guide will help you...

## Installation

First, install the dependencies...
```

--------------------------------

### Configuration Precedence Example

Source: https://rumdl.dev/global-settings

Demonstrates how command-line arguments override settings defined in a configuration file.

```toml
[global]
disable = ["MD013", "MD033"]
exclude = ["node_modules", "build"]
```

```bash
rumdl check --disable MD001,MD013 --exclude "temp/**" docs/
```

--------------------------------

### Correct HTML Heading Example

Source: https://rumdl.dev/md041

A valid document starting with an HTML H1 tag.

```html
<h1>Getting Started Guide</h1>

Welcome to our documentation! This guide will help you...
```

--------------------------------

### Correct Markdown Heading Example

Source: https://rumdl.dev/md041

A valid document starting with a top-level Markdown heading.

```markdown
# Getting Started Guide

Welcome to our documentation! This guide will help you...
```

--------------------------------

### Incorrect Document Start Example 2

Source: https://rumdl.dev/md041

An invalid document that lacks a top-level heading entirely.

```markdown
This project provides tools for...

Some more content here.
```

--------------------------------

### Mixed Documentation Project configuration

Source: https://rumdl.dev/global-settings

Example showing a global default flavor with specific overrides for different documentation types.

```toml
[global]
flavor = "standard"  # Default for files not matching any pattern

[per-file-flavor]
# MkDocs documentation
"docs/**/*.md" = "mkdocs"

# React components with MDX
"src/components/**/*.mdx" = "mdx"

# Jupyter/Quarto notebooks
"notebooks/**/*.qmd" = "quarto"

# Keep README and CHANGELOG as standard
"README.md" = "standard"
"CHANGELOG.md" = "standard"
```

--------------------------------

### Example .editorconfig and .rumdl.toml integration

Source: https://rumdl.dev/global-settings

Shows how to define properties in .editorconfig and enable them in .rumdl.toml.

```toml
# .editorconfig
root = true

[*.md]
max_line_length = 100
indent_size = 4

```

```toml
# .rumdl.toml
[global]
editorconfig = true

```

--------------------------------

### Correct table without leading and trailing pipes

Source: https://rumdl.dev/md055

Example of a table using no pipes at the start or end of rows.

```markdown
Name     | Role      | Department
-------- | --------- | ----------
Alice    | Manager   | Sales
Bob      | Developer | IT
```

--------------------------------

### Correct table with leading and trailing pipes

Source: https://rumdl.dev/md055

Example of a table using pipes at both the start and end of every row.

```markdown
| Name     | Role      | Department |
| -------- | --------- | ---------- |
| Alice    | Manager   | Sales      |
| Bob      | Developer | IT         |
```

--------------------------------

### Example: full Format Output

Source: https://rumdl.dev/usage/cli

Sample output of the 'full' format, showing source lines with caret underlines highlighting the violation.

```text
MD013 Line length 95 exceeds 80 characters
 --> README.md:42:81
   |
42 | This is a long line that exceeds the configured maximum line length ...
   |                                                                     ^^^
   |
```

--------------------------------

### Incorrect unclosed code block

Source: https://rumdl.dev/md046

Example showing a missing closing fence before a new code block starts.

```javascript
const api = require('our-api');
api.connect();

```python
print("hello")
```
```

--------------------------------

### Tight items with loose continuation configuration and example

Source: https://rumdl.dev/md076

Configuration and list example demonstrating how to allow blank lines around continuation paragraphs while maintaining tight inter-item spacing.

```toml
[MD076]
style = "tight"
allow-loose-continuation = true
```

```markdown
- List item.

  Continuation paragraph that provides more detail.

- Another item.

  Its continuation paragraph.

- Simple item.
- Another simple item.
```

--------------------------------

### Correct HTML Comment and Heading Example

Source: https://rumdl.dev/md041

A valid document starting with an HTML comment followed by a top-level Markdown heading.

```markdown
<!-- This is a comment -->
# Getting Started Guide

Welcome to our documentation! This guide will help you...
```

--------------------------------

### Customized configuration

Source: https://rumdl.dev/md058

An example configuration requiring two blank lines before the table.

```ini
[MD058]
minimum-before = 2  # Require 2 blank lines before
minimum-after = 1  # Require 1 blank line after

```

--------------------------------

### rumdl version command examples

Source: https://rumdl.dev/usage/cli

Shows how to display short version information and detailed version information.

```bash
rumdl --version                  # Short version
rumdl version                    # Detailed version info
```

--------------------------------

### Definition List Reflow Example

Source: https://rumdl.dev/md013

Illustrates how definition list text is reflowed and indented to the definition's start column, with a line length of 40.

```markdown
# Before
Term
: Aliquam metus eros, pretium sed nulla venenatis.
: Duis mollis.

# After
Term
: Aliquam metus eros, pretium sed
    nulla venenatis.
: Duis mollis.
```

--------------------------------

### MD040 configuration example

Source: https://rumdl.dev/md040

Configuration settings for MD040, including style mode and preferred language aliases.

```toml
[MD040]
# Language label normalization mode
# - "disabled" (default): Only check for missing language
# - "consistent": Normalize to most prevalent alias per language
style = "disabled"

# Override preferred label for specific languages
# Keys are GitHub Linguist canonical names, values are your preferred alias
preferred-aliases = { Shell = "bash", JavaScript = "js" }
```

--------------------------------

### Example with list-items enabled

Source: https://rumdl.dev/md031

Demonstrates the required spacing when list-items is set to true.

```markdown
1. First item

   ```python
   code_in_list()
   ```

1. Second item
```

--------------------------------

### Example 1: Documentation with Code Examples

Source: https://rumdl.dev/inline-configuration

Example of disabling line length rules for a long curl command in API documentation.

```markdown
# API Documentation

The API follows standard REST conventions.

<!-- rumdl-disable MD013 -->

```bash
curl -X POST <https://api.example.com/v1/users/create> -H "Authorization: Bearer very-long-token-that-would-normally-violate-line-length" -d '{"name": "John Doe"}'
```

<!-- rumdl-enable MD013 -->

Regular documentation continues here.
```

--------------------------------

### Example .rumdl.toml configuration

Source: https://rumdl.dev/getting-started/quickstart

A sample configuration file demonstrating rule exclusions, line length limits, and rule-specific settings.

```toml
[global]
# Exclude files/directories
exclude = ["node_modules", "vendor", ".git"]

# Set line length limit
line-length = 120

[MD013]  # Line length
line_length = 120
code_blocks = false  # Don't check code blocks

[MD033]  # No inline HTML
allowed_elements = ["br", "details", "summary"]

[MD041]  # First line heading
enabled = false  # Disable this rule
```

--------------------------------

### Configure per-file-ignores for Mixed Documentation Sources

Source: https://rumdl.dev/global-settings

Example configuration for projects containing both third-party and legacy documentation.

```toml
[per-file-ignores]
"vendor/**/*.md" = ["MD013", "MD033", "MD041"]  # Third-party docs
"legacy/**/*.md" = ["MD003", "MD022", "MD032"]  # Old docs with different style
```

--------------------------------

### Verify Installation

Source: https://rumdl.dev/getting-started/installation

Check the installed version of rumdl.

```bash
rumdl --version
```

--------------------------------

### CLI usage examples

Source: https://rumdl.dev/flavors/myst

Commands to check documentation using the myst or mystmd flavors.

```bash
rumdl check --flavor myst docs/
rumdl check --flavor mystmd docs/
```

--------------------------------

### Install with Nix

Source: https://rumdl.dev/getting-started/installation

Install rumdl using the Nix package manager.

```bash
nix-channel --update
nix-env --install --attr nixpkgs.rumdl
```

--------------------------------

### Applying pad-width to every style

Source: https://rumdl.dev/md060

Configuration example showing how pad-width applies to a style, such as a tight table.

```toml
[MD060]
enabled = true
style = "any"
pad-width = 1  # a detected `tight` table gains the padding tight leaves out
```

--------------------------------

### Install with Homebrew

Source: https://rumdl.dev/getting-started/installation

Install rumdl on macOS or Linux using Homebrew.

```bash
brew install rumdl
```

--------------------------------

### Correct link examples

Source: https://rumdl.dev/md095

Examples of links that do not trigger the MD095 rule.

```markdown
[Project](https://example.com/docs)
<https://example.com/docs>
<a href="https://example.com/docs">Project</a>
```

--------------------------------

### TOML Configuration (.rumdl.toml)

Source: https://rumdl.dev/global-settings

Example of a full .rumdl.toml configuration file showing global settings, file exclusions, and per-file overrides.

```toml
[global]
# Disable specific rules
disable = ["MD013", "MD033"]

# Add opt-in rules on top of defaults (additive)
extend-enable = ["MD060", "MD063"]

# Exclude files and directories
exclude = [
    "node_modules",
    "build",
    "dist",
    "*.tmp.md",
    "docs/generated/**"
]

# Include only specific files
include = [
    "README.md",
    "docs/**/*.md",
    "**/*.markdown"
]

# Don't respect .gitignore files
respect-gitignore = false

# Set global line length (used by MD013 and other line-length rules)
line-length = 120

# Set markdown flavor (standard, gfm, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, myst, hugo, mdg, gh-aw)
flavor = "mkdocs"

# Per-file flavor overrides (pattern → flavor)
[per-file-flavor]
"**/*.mdx" = "mdx"
"notebooks/**/*.qmd" = "quarto"

# Disable specific rules for specific files
[per-file-ignores]
"README.md" = ["MD033"]  # Allow inline HTML in README
"docs/api/**/*.md" = ["MD013", "MD041"]  # Generated API docs
"SUMMARY.md" = ["MD025"]  # MkDocs/mdBook table of contents
```

--------------------------------

### Correct content examples

Source: https://rumdl.dev/md084

Examples of content without invisible characters.

```markdown
AB
```

```markdown
Starts with visible text
```

```markdown
left right
```

--------------------------------

### Correct heading examples

Source: https://rumdl.dev/md026

Examples of headings that comply with the MD026 rule.

```markdown
# Introduction

## What is Markdown?

### FAQ: Frequently Asked Questions

#### Step 1: Getting Started

##### Chapter 2: Configuration

```

--------------------------------

### MD041 Configuration Options

Source: https://rumdl.dev/md041

Example configuration for the MD041 rule in a configuration file.

```toml
[MD041]
level = 1  # Heading level required (1-6, default: 1)
front-matter-title = "title"  # Front matter field to use as title
front-matter-title-pattern = "^(title|header):"  # Regex pattern to match title fields in front matter
allow-preamble = false  # Allow content before the first heading (default: false)
fix = false  # Enable auto-fix (default: false)
```

--------------------------------

### Install rumdl

Source: https://rumdl.dev/mdformat-comparison

Installation commands for rumdl using various package managers.

```bash
# Any of these:
cargo install rumdl
pip install rumdl
brew install rumdl
uv tool install rumdl
```

--------------------------------

### Install with mise

Source: https://rumdl.dev/getting-started/installation

Manage rumdl versions using mise.

```bash
# List available versions
mise ls-remote rumdl

# Install the latest version
mise install rumdl

# Use a specific version for the project
mise use rumdl@latest
```

--------------------------------

### Install on Arch Linux

Source: https://rumdl.dev/getting-started/installation

Install rumdl on Arch Linux using pacman.

```bash
pacman -S rumdl
```

--------------------------------

### Example configuration for .rumdl.toml

Source: https://rumdl.dev/md074

Configuration settings for MD074 within the .rumdl.toml file, enabling warnings for missing files, omitted files, and absolute links.

```toml
# .rumdl.toml
[global]
flavor = "mkdocs"

[MD074]
not-found = "warn"
omitted-files = "warn"
absolute-links = "warn"

```

--------------------------------

### Install with pip

Source: https://rumdl.dev/getting-started/installation

Install rumdl using the Python pip package manager.

```bash
pip install rumdl
```

--------------------------------

### Configure Python linting and formatting

Source: https://rumdl.dev/code-block-tools

Example configuration for Python using black for both linting and formatting.

```toml
[code-block-tools.languages]
python = { lint = ["black"], format = ["black"] }
```

--------------------------------

### Install with cargo

Source: https://rumdl.dev/getting-started/installation

Install rumdl using the Rust cargo package manager.

```bash
cargo install rumdl
```

--------------------------------

### Integrate with VS Code

Source: https://rumdl.dev/getting-started/quickstart

Command to set up real-time linting in VS Code.

```bash
rumdl vscode
```

--------------------------------

### Configure include in global settings

Source: https://rumdl.dev/global-settings

Example configuration for the include setting within a global configuration file, supporting specific files, directory paths, and glob patterns.

```toml
[global]
include = [
    "README.md",             # Include specific file
    "docs/**/*.md",          # Include all .md files in docs/
    "guides",                # Include a directory: the Markdown files beneath it
    "**/*.markdown",         # Include all .markdown files
    "CHANGELOG.md",          # Include specific files
    "src/**/*.md",           # Include documentation in source
    "**/*.md.jinja",         # Include templates with a non-standard extension
]
```
Tokens:
Raw