### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Neovim nvim-lspconfig Setup Source: https://rumdl.dev/usage/editors Setup using the nvim-lspconfig plugin. ```lua require('lspconfig').rumdl.setup{} ``` -------------------------------- ### 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 ``` -------------------------------- ### 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. ```bash curl -X POST -H "Authorization: Bearer very-long-token-that-would-normally-violate-line-length" -d '{"name": "John Doe"}' ``` Regular documentation continues here. ``` -------------------------------- ### 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. ``` -------------------------------- ### 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 ``` -------------------------------- ### Verify Tool Installation Source: https://rumdl.dev/code-block-tools Checks if a tool is installed and available in the system PATH. ```bash command -v ruff # Should show path ruff --version # Should show version ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Tag syntax example Source: https://rumdl.dev/md018 Example content demonstrating how various tag patterns are handled when tags are enabled. ```markdown # Real Heading #todo this is a tag #project/active nested tag #3d_printing tag starting with a digit ##Introduction ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Install with Homebrew Source: https://rumdl.dev/getting-started/installation Install rumdl on macOS or Linux using Homebrew. ```bash brew install rumdl ``` -------------------------------- ### 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 ``` -------------------------------- ### Correct content examples Source: https://rumdl.dev/md084 Examples of content without invisible characters. ```markdown AB ``` ```markdown Starts with visible text ``` ```markdown left right ``` -------------------------------- ### 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... ``` -------------------------------- ### Fixed link usage examples Source: https://rumdl.dev/md042 Examples showing how to resolve MD042 violations by adding text or placeholder URLs. ```markdown [Link](https://example.com) [Click here](#) [Link](https://example.com) [Visit our website](#) ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### Correct heading spacing example Source: https://rumdl.dev/md022 An example showing headings correctly surrounded by blank lines. ```markdown Some introductory text here. # Main Heading This is the content under the main heading. ## Subheading More content follows here. ### Another Section And even more content. ``` -------------------------------- ### 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 ``` -------------------------------- ### 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) ``` -------------------------------- ### 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 ``` -------------------------------- ### Incorrect npm install command Source: https://rumdl.dev/md014 An example of a shell command that is missing its expected output. ```shell $ npm install ``` -------------------------------- ### Install with winget Source: https://rumdl.dev/getting-started/installation Install rumdl on Windows using the winget package manager. ```bash winget install --id rvben.rumdl --exact ``` -------------------------------- ### Correct list spacing example Source: https://rumdl.dev/md030 Example of list formatting that satisfies the MD030 rule. ```markdown * Unordered list item with one space * Another item 1. Ordered list item with one space 2. Another item ``` -------------------------------- ### 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... ``` -------------------------------- ### YAML - Correct Source: https://rumdl.dev/md072 An example of YAML frontmatter with keys sorted alphabetically. ```yaml --- author: John Doe date: 2024-01-15 title: My Document --- # Heading ``` -------------------------------- ### 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

Getting Started Guide

Welcome to our documentation! This guide will help you... ``` -------------------------------- ### Install only in GitHub Actions Source: https://rumdl.dev/usage/ci-cd Installs the binary without running the built-in linting, allowing for custom build steps. ```yaml - uses: rvben/rumdl@v0 with: install-only: true - run: make lint ``` -------------------------------- ### 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... ``` -------------------------------- ### 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" ``` -------------------------------- ### 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. ``` -------------------------------- ### Configure per-file-ignores for MkDocs/mdBook Source: https://rumdl.dev/global-settings Example configuration for projects using MkDocs or mdBook. ```toml [per-file-ignores] "SUMMARY.md" = ["MD025"] # Table of contents has multiple H1 headings ``` -------------------------------- ### 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 ``` -------------------------------- ### CircleCI configuration Source: https://rumdl.dev/usage/ci-cd Example configuration for .circleci/config.yml. ```yaml version: 2.1 jobs: lint: docker: - image: cimg/python:3.12 steps: - checkout - run: name: Install rumdl command: pip install rumdl - run: name: Lint Markdown command: rumdl check . workflows: main: jobs: - lint ``` -------------------------------- ### 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 frontmatter formatting Source: https://rumdl.dev/md071 An example showing the correct usage with a blank line after the frontmatter. ```markdown --- title: My Document author: John Doe --- # Heading Content here. ``` -------------------------------- ### 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 ... | ^^^ | ``` -------------------------------- ### Correct list indentation examples Source: https://rumdl.dev/md005 Examples of correctly formatted lists using consistent 2-space, 3-space, and 4-space indentation patterns. ```markdown * Item 1 * Item 2 * Nested item (2 spaces) * Another nested item * Deep nested (4 spaces) * Item 3 1. First item 2. Second item 1. Nested ordered (3 spaces - aligns with parent text) 2. Another nested 3. Third item # Also correct with 4-space indentation: * Item A * Nested with 4 spaces * Double nested with 8 spaces * Consistent 4-space pattern ``` -------------------------------- ### 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") ``` ``` -------------------------------- ### 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 # Getting Started Guide Welcome to our documentation! This guide will help you... ``` -------------------------------- ### JSON - Correct Source: https://rumdl.dev/md072 An example of JSON frontmatter with keys sorted alphabetically. ```json { "author": "John Doe", "title": "My Document" } # Heading ``` -------------------------------- ### Fixed style example Source: https://rumdl.dev/md054 Shows the corrected version of the mixed styles example, where all links are converted to a consistent inline style. ```markdown Check out [our website](https://example.com) for more info. See the [documentation](https://docs.example.com) for details. View our [contact page](https://example.com/contact). ``` -------------------------------- ### 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. ``` -------------------------------- ### 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 ``` -------------------------------- ### Configuration for MD031 Source: https://rumdl.dev/md031 Example configuration for the MD031 rule, including the list-items setting. ```ini [MD031] list-items = true # Also require blank lines in lists (default: true) ``` -------------------------------- ### Heading spacing example Source: https://rumdl.dev/md012 An example showing two blank lines before a heading, which is permitted when MD022 is configured with lines-above = 2. ```markdown # Title ## Section ``` -------------------------------- ### TOML - Correct Source: https://rumdl.dev/md072 An example of TOML frontmatter with keys sorted alphabetically. ```toml +++ author = "John Doe" title = "My Document" +++ # Heading ``` -------------------------------- ### Configuration for MD055 Source: https://rumdl.dev/md055 Example configuration block for the MD055 rule. ```ini [MD055] style = "consistent" # Options: see below ``` -------------------------------- ### 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" } ``` -------------------------------- ### Azure Pipelines configuration Source: https://rumdl.dev/usage/ci-cd Example configuration for azure-pipelines.yml. ```yaml trigger: - main pool: vmImage: ubuntu-latest steps: - task: UsePythonVersion@0 inputs: versionSpec: '3.12' - script: pip install rumdl displayName: Install rumdl - script: rumdl check . displayName: Lint Markdown ``` -------------------------------- ### Language and content policy configuration Source: https://rumdl.dev/md061 Example configuration for enforcing content policies. ```toml [MD061] terms = ["damn", "hell"] case-sensitive = false ``` -------------------------------- ### 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 ``` -------------------------------- ### Verify Installation Source: https://rumdl.dev/getting-started/installation Check the installed version of rumdl. ```bash rumdl --version ``` -------------------------------- ### Front matter integration example Source: https://rumdl.dev/md025 Example showing how a YAML front matter title acts as the document's H1. ```markdown --- title: My Blog Post date: 2024-01-15 --- Content starts here without an H1 heading. ## First Section This is valid because the front matter title counts as the H1. ``` -------------------------------- ### 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 ``` -------------------------------- ### MD081 Configuration Example Source: https://rumdl.dev/md081 Example configuration for the MD081 rule, defining the target span types and thresholds for emphasis frequency. ```toml [MD081] # Which spans to count: "strong" (bold), "emphasis" (italic), or "all". targets = "strong" # Flag a paragraph with more than this many emphasis spans (0 = off). max-per-paragraph = 4 # Flag a run of more than this many adjacent emphasis spans (0 = off). max-consecutive = 3 ``` -------------------------------- ### Start-Indented Configuration Source: https://rumdl.dev/md007 Configuration and example for allowing the first level of lists to be indented. ```toml [MD007] indent = 2 start-indented = true start-indent = 4 ``` ```markdown Some paragraph text. * First level item (4 spaces indent) * Second level item (6 spaces total: 4 + 2) * Third level item (8 spaces total: 4 + 2 + 2) * Another first level item ``` -------------------------------- ### 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/ ``` -------------------------------- ### 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 ``` -------------------------------- ### Configuration for MD048 Source: https://rumdl.dev/md048 Example configuration for the MD048 rule in a markdownlint configuration file. ```toml [MD048] style = "consistent" # Options: "consistent", "backtick", "tilde" ``` -------------------------------- ### GitLab CI configuration Source: https://rumdl.dev/usage/ci-cd Example configuration for .gitlab-ci.yml using a Python image. ```yaml lint:markdown: image: python:3.12-slim before_script: - pip install rumdl script: - rumdl check . ``` -------------------------------- ### Correct link examples Source: https://rumdl.dev/md095 Examples of links that do not trigger the MD095 rule. ```markdown [Project](https://example.com/docs) Project ``` -------------------------------- ### 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 ``` -------------------------------- ### Line length measurement examples with 80 character limit Source: https://rumdl.dev/md013 Examples showing how text with and without URLs is evaluated against an 80-character limit. ```markdown See the [installation guide](https://example.com/docs/getting-started/installation/v2) for details. This is already a very long sentence with lots of words that pushes past the limit even [without](https://example.com) the URL. ``` -------------------------------- ### mdformat Configuration Source: https://rumdl.dev/mdformat-comparison Example configuration for mdformat using .mdformat.toml. ```toml # .mdformat.toml wrap = 80 number = true end_of_line = "lf" ``` -------------------------------- ### 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" ``` -------------------------------- ### 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 pip Source: https://rumdl.dev/getting-started/installation Install rumdl using the Python pip package manager. ```bash pip 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 ``` -------------------------------- ### Install with cargo Source: https://rumdl.dev/getting-started/installation Install rumdl using the Rust cargo package manager. ```bash cargo install rumdl ``` -------------------------------- ### 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 ] ``` -------------------------------- ### Start rumdl LSP server with options Source: https://rumdl.dev/lsp Shows how to launch the rumdl LSP server. Default uses stdio for editor integration; --config specifies a custom config file; --verbose enables debug logging; --port enables TCP mode for debugging. ```bash # Default: use stdio (for editor integration) rumdl server # With custom config rumdl server --config .rumdl.toml # Verbose logging (for debugging) rumdl server --verbose # TCP mode (for debugging) rumdl server --port 9257 ``` -------------------------------- ### Correct heading formatting Source: https://rumdl.dev/md093 Examples of headings without inline markup. ```markdown ## Method map() ### Practice ## The .env file ``` -------------------------------- ### Enable opt-in rules in configuration Source: https://rumdl.dev/global-settings Example of using extend-enable in a configuration file to activate specific opt-in rules without replacing the default rule set. ```toml [global] extend-enable = ["MD060", "MD063"] ``` -------------------------------- ### MD046 configuration Source: https://rumdl.dev/md046 Example configuration for the MD046 rule in a markdownlint file. ```toml [MD046] style = "consistent" # Options: "consistent", "fenced", "indented" ``` -------------------------------- ### Correct ordered list example (one style) Source: https://rumdl.dev/md029 Recommended style using '1.' for all list items. ```markdown 1. First item 1. Second item 1. Third item ``` -------------------------------- ### Gherkin table example Source: https://rumdl.dev/md046 Example of a Gherkin table that is excluded from indented-code detection. ```gherkin | start | eat | | ----- | --- | ``` -------------------------------- ### Incorrect ordered list example Source: https://rumdl.dev/md029 Example of inconsistent numbering that will be flagged by the rule. ```markdown 1. First item 3. Second item 5. Third item ``` -------------------------------- ### Preview rumdl configuration import Source: https://rumdl.dev/markdownlint-comparison Dry-run import of an existing .markdownlint.json to preview the conversion before writing native configuration. ```bash rumdl import --dry-run .markdownlint.json ``` -------------------------------- ### TOML - Incorrect Source: https://rumdl.dev/md072 An example of TOML frontmatter with keys that are not sorted alphabetically. ```toml +++ title = "My Document" author = "John Doe" +++ # Heading ``` -------------------------------- ### Configure flavor in global settings Source: https://rumdl.dev/global-settings Example of setting the flavor to mkdocs within the global configuration file. ```toml [global] flavor = "mkdocs" # Use MkDocs flavor ``` -------------------------------- ### Fixed heading examples Source: https://rumdl.dev/md026 The result of applying the MD026 rule to the incorrect examples. ```markdown # This is a sentence ## Random heading ### This seems wrong #### Important ##### Ending with colon ``` -------------------------------- ### Correct heading usage example Source: https://rumdl.dev/md024 An example of a document structure where all headings are unique. ```markdown # Project Setup ## Installing Dependencies Details about npm install... ## Configuring the Environment Details about environment setup... ## Running Tests How to run the test suite... ``` -------------------------------- ### Custom configuration with allowed codepoints Source: https://rumdl.dev/md088 Example configuration enabling both quote and dash normalization while preserving specific prime characters. ```ini [MD088] enabled = true normalize-quotes = true normalize-dashes = true allow = ["U+2032", "U+2033"] ``` -------------------------------- ### Manual installation via pip Source: https://rumdl.dev/usage/ci-cd Installs rumdl using the Python package manager. ```yaml - name: Install rumdl run: pip install rumdl - name: Lint run: rumdl check . ``` -------------------------------- ### Manual installation via Cargo Source: https://rumdl.dev/usage/ci-cd Installs rumdl using the Rust package manager. ```yaml jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Install rumdl run: cargo install rumdl - name: Lint run: rumdl check . ``` -------------------------------- ### Incorrect usage examples Source: https://rumdl.dev/md087 Examples of disable comments that are reported as incorrect because they do not suppress any findings. ```markdown A short line. ``` ```markdown # Title A document with no consecutive blank lines in it. ``` -------------------------------- ### rumdl config command examples Source: https://rumdl.dev/usage/cli Shows how to display the merged configuration, default values only, or non-default values only. ```bash rumdl config # Show merged configuration rumdl config --defaults # Show default values only rumdl config --no-defaults # Show non-default values only ``` -------------------------------- ### Configure global paths with home directory expansion Source: https://rumdl.dev/global-settings Example of using the '~/' prefix in a 'rumdl.toml' configuration file to specify paths relative to the user's home directory. ```toml [global] exclude = ["~/.cursor/plans"] cache-dir = "~/.cache/rumdl" ``` -------------------------------- ### Fixed closed heading examples Source: https://rumdl.dev/md021 The result of applying automatic fixes to the incorrect examples. ```markdown # Heading 1 # ## Heading 2 ## ### Heading 3 ### #### Heading 4 #### ##### Heading 5 ##### ``` -------------------------------- ### Example frontmatter with link fragments Source: https://rumdl.dev/md051 Demonstrates how frontmatter values are interpreted as links when check-frontmatter is enabled. ```yaml --- anchor: '#setup' # must match a heading in this document guide: ./install.md#setup # must match a heading in install.md canonical: https://example.com/a.md#setup # external, not checked title: Node.js # prose, not read as a link --- ``` -------------------------------- ### Fixed heading structure example Source: https://rumdl.dev/md001 The corrected version of the incorrect heading structure example. ```markdown # Title ## Section 1.1 ### Subsection ``` -------------------------------- ### Math blocks Source: https://rumdl.dev/flavors/quarto Examples of LaTeX math blocks and inline math syntax. ```markdown $$ E = mc^2 $$ Inline math $\alpha + \beta$ is also recognized. ``` -------------------------------- ### Incorrect heading structure example Source: https://rumdl.dev/md001 An example of invalid heading hierarchy where levels are skipped. ```markdown # Title ### Section 1.1 (skipped level 2) ##### Subsection (skipped levels 2, 3, and 4) ``` -------------------------------- ### Example: text Format Output (Default) Source: https://rumdl.dev/usage/cli Sample output of the default 'text' format, one line per warning with file:line:col and rule code. ```text README.md:42:81: [MD013] Line length 95 exceeds 80 characters ``` -------------------------------- ### Correct Markdown link syntax Source: https://rumdl.dev/md011 Examples of properly formatted Markdown links. ```markdown Check out [our documentation](https://docs.example.com) Visit the [GitHub repository](https://github.com/example/repo) Contact us at [support@example.com](mailto:support@example.com) ``` -------------------------------- ### Install on Android (Termux) Source: https://rumdl.dev/getting-started/installation Install rumdl on Android using Termux by enabling the TUR repository. ```bash # Enable TUR repo first pkg install tur-repo # Then install rumdl pkg install rumdl ``` -------------------------------- ### Configure GitHub Actions with pip cache Source: https://rumdl.dev/usage/ci-cd Use the setup-python action with the cache parameter set to 'pip' to speed up dependency installation for rumdl. ```yaml - uses: actions/setup-python@v5 with: python-version: '3.12' cache: 'pip' - run: pip install rumdl ``` -------------------------------- ### Correct CJK spacing examples Source: https://rumdl.dev/md089 The corrected versions of the previous examples with proper spacing inserted. ```markdown 日本語 english ひらがな 今天出去買菜花了 5000 元。 한글 english 한글 角度為 90° 的角 ``` -------------------------------- ### Configure CI/CD pipeline Source: https://rumdl.dev/getting-started/quickstart Example GitHub Actions workflow for linting Markdown files. ```yaml name: Lint Markdown on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: rvben/rumdl@v0 ``` -------------------------------- ### Download Windows Binary Source: https://rumdl.dev/getting-started/installation Download and extract the pre-built binary for Windows using PowerShell. ```powershell # PowerShell Invoke-WebRequest -Uri "https://github.com/rvben/rumdl/releases/latest/download/rumdl-windows-x86_64.zip" -OutFile "rumdl.zip" Expand-Archive -Path "rumdl.zip" -DestinationPath "$env:USERPROFILE\.rumdl" # Add to PATH manually ``` -------------------------------- ### Incorrect invisible character examples Source: https://rumdl.dev/md084 Examples of content containing invisible characters that trigger the rule. ```markdown A​‌B ``` ```markdown ​Starts with hidden char ``` ```markdown left ⁠ right ``` -------------------------------- ### Example src/lib.rs with doc comments Source: https://rumdl.dev/rust-doc-comments A sample Rust file with doc comments that contain Markdown lint issues. Used to demonstrate rumdl check and fmt behavior. ```rust //! #Parsing utilities //! Helpers for reading input. /// Parses `input`. /// # Errors /// Returns [`ParseError`] when `input` is empty. pub fn parse(input: &str) -> Result<(), ParseError> { todo!() } ``` -------------------------------- ### Incorrect mojibake example Source: https://rumdl.dev/md083 An example of text containing corrupted characters due to encoding issues. ```markdown # Café menu This line contains a broken dash – and a broken apostrophe ’. ``` -------------------------------- ### Fixed list spacing example Source: https://rumdl.dev/md030 The result of applying automatic fixes to the incorrect list example. ```markdown * Unordered list item with one space * Another item with one space 1. Ordered list item with one space 2. Another item with one space ``` -------------------------------- ### Incorrect heading examples Source: https://rumdl.dev/md026 Examples of headings that trigger the MD026 rule due to trailing punctuation. ```markdown # This is a sentence. ## Random heading; ### This seems wrong, #### Important! ##### Ending with colon: ``` -------------------------------- ### Configure on-error globally and per-language Source: https://rumdl.dev/code-block-tools Example configuration showing a global 'warn' setting and a specific 'skip' override for the shell language. ```toml [code-block-tools] on-error = "warn" # Global override; the default is "fail" [code-block-tools.languages] shell = { lint = ["shellcheck"], on-error = "skip" } # Override for shell ``` -------------------------------- ### Fixed list indentation examples Source: https://rumdl.dev/md005 The corrected versions of the previously shown incorrect list examples. ```markdown * Item 1 * Item 2 * Nested * Another 1. First item 2. Second item 1. Nested ``` -------------------------------- ### Correct heading structure example Source: https://rumdl.dev/md001 An example of a valid heading hierarchy where levels increment by one. ```markdown # Title ## Chapter 1 ### Section 1.1 ### Section 1.2 ## Chapter 2 ### Section 2.1 ``` -------------------------------- ### File Selection Configuration Source: https://rumdl.dev/global-settings Example configuration showing how include and exclude patterns interact with respect-gitignore settings to filter files. ```toml [global] include = ["docs/**/*.md", "README.md"] exclude = ["docs/temp/**", "*.draft.md"] respect-gitignore = true ``` -------------------------------- ### Tag Line Examples Source: https://rumdl.dev/flavors/mdg Examples of lines containing backtick-wrapped tags recognized by the Gherkin pattern. ```markdown `@billing` `@critical` ## Scenario: Reject an expired card ``` ```markdown `@comment_tag1` #a comment prefix `@tag with spaces` suffix ``` -------------------------------- ### Global configuration using alias Source: https://rumdl.dev/flavors/azure_devops Setting the flavor globally using the ado alias. ```toml [global] flavor = "ado" ``` -------------------------------- ### MD073 Configuration Settings Source: https://rumdl.dev/md073 Example configuration for the MD073 rule, including enabling the rule and setting heading level constraints. ```toml [MD073] # Enable the rule (opt-in, disabled by default) enabled = true # Minimum heading level to include (default: 2) min-level = 2 # Maximum heading level to include (default: 4) max-level = 4 # Whether TOC order must match document order (default: true) enforce-order = true # Spaces per indentation level (default: from MD007, or 2) # indent = 4 ``` -------------------------------- ### Exception: Start of Document Source: https://rumdl.dev/md065 Horizontal rules at the start of a document do not require a preceding blank line. ```markdown --- Content after horizontal rule. ``` -------------------------------- ### rumdl rule command examples Source: https://rumdl.dev/usage/cli Shows how to list all rules, view details for a specific rule by name or alias, discover rule categories, and output rule details in JSON format with optional full documentation. ```bash rumdl rule # List all rules rumdl rule MD013 # Show details for specific rule rumdl rule line-length # Use rule alias rumdl rule --list-categories # Discover rule categories rumdl rule MD013 --output-format json rumdl rule MD013 --output-format json --explain ``` -------------------------------- ### Incorrect link examples Source: https://rumdl.dev/md095 Examples of links that trigger the MD095 rule due to confusable Unicode characters. ```markdown [Project](https://еxample.com/docs) Project ``` -------------------------------- ### Correct usage example Source: https://rumdl.dev/md087 An example of a correctly used disable comment that suppresses a valid rule violation. ```markdown A line so long that it genuinely exceeds the configured limit, which is what the comment is for. ``` -------------------------------- ### Fixed heading usage example Source: https://rumdl.dev/md024 The previous incorrect example updated to use unique, descriptive headings. ```markdown # Project Setup ## Installing Dependencies Details about npm install... ## Environment Configuration Details about environment setup... ## Test Setup How to run the test suite... ``` -------------------------------- ### Correct closed heading examples Source: https://rumdl.dev/md021 Examples of closed headings that follow the MD021 rule with single spacing. ```markdown # Heading 1 # ## Heading 2 ## ### Heading 3 ### #### Heading 4 #### ##### Heading 5 ##### ###### Heading 6 ###### ``` -------------------------------- ### Enable shortcut-syntax configuration Source: https://rumdl.dev/md052 Configuration to enable checking of shortcut reference syntax. ```toml [MD052] shortcut-syntax = true # Enable checking of shortcut references ``` -------------------------------- ### Correct list indentation example Source: https://rumdl.dev/md007 This example demonstrates the expected 2-space indentation for nested list items. ```markdown * Chapter 1 * Section 1.1 * Subsection 1.1.1 * Subsection 1.1.2 * Section 1.2 * Chapter 2 * Section 2.1 ``` -------------------------------- ### Inline Rule Configuration Examples Source: https://rumdl.dev/inline-configuration Demonstrates how to disable rules using IDs or aliases, including disabling multiple rules at once. ```markdown ``` -------------------------------- ### Build rumdl and run benchmark scripts Source: https://rumdl.dev/benchmarks Commands to build the rumdl binary and run the benchmark and chart generation scripts. Requires Rust, Python, Node.js, uv, and hyperfine, plus a checkout of the Rust Book next to the rumdl repository. ```bash cargo build --release python3 scripts/benchmark_cold_start.py --target ../rust-book uv run --with matplotlib python3 scripts/generate_benchmark_chart.py ``` -------------------------------- ### Correct indentation example Source: https://rumdl.dev/md010 An example of a list structure using spaces for indentation, which complies with the MD010 rule. ```markdown * Shopping list * Fruits * Apples * Bananas * Vegetables * Carrots * Broccoli Remember to check for freshness! ``` -------------------------------- ### Table Row Examples Source: https://rumdl.dev/flavors/mdg Examples of Gherkin table rows identified by leading whitespace followed by a pipe. ```markdown #### Examples: | start | eat | left | | ----- | --- | ---- | | 12 | 5 | 7 | ``` -------------------------------- ### Structure Heading Examples Source: https://rumdl.dev/flavors/mdg Examples of ATX headings recognized as Gherkin structure headings by the presence of a colon. ```markdown # Feature: Checkout ## Rule: Registered customers ### Scenario Outline: Buy an item #### Examples: Valid cards ```