{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Config",
"description": "rumdl configuration for linting Markdown files. Rules can be configured individually using [MD###] sections with rule-specific options.",
"type": "object",
"properties": {
"extends": {
"description": "Path to a base config file to inherit settings from.\nSupports relative paths, absolute paths, `~/` for the home directory, and\n`$VAR` / `${VAR}` environment-variable expansion (a literal `$` is written `$$`).\nExample: `extends = \"../base.rumdl.toml\"` or `extends = \"$GEM_PATH/base.rumdl.toml\"`",
"type": [
"string",
"null"
]
},
"global": {
"description": "Global configuration options",
"$ref": "#/$defs/GlobalConfig",
"default": {
"enable": [],
"disable": [],
"exclude": [],
"include": [],
"respect-gitignore": true,
"line-length": 80,
"fixable": [],
"unfixable": [],
"flavor": "standard",
"force-exclude": false,
"cache": true,
"extend-enable": [],
"extend-disable": [],
"editorconfig": false
}
},
"per-file-ignores": {
"description": "Per-file rule ignores: maps file patterns to lists of rules to ignore.\nPatterns are relative to the project root; a leading `~/` expands to the\nhome directory and absolute paths are matched as written.\nExample: { \"README.md\": [\"MD033\"], \"docs/**/*.md\": [\"MD013\"] }",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"default": {}
},
"per-file-flavor": {
"description": "Per-file flavor overrides: maps file patterns to Markdown flavors.\nPatterns are relative to the project root; a leading `~/` expands to the\nhome directory and absolute paths are matched as written.\nExample: { \"docs/**/*.md\": MkDocs, \"**/*.mdx\": MDX }\nUses IndexMap to preserve config file order for \"first match wins\" semantics",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/MarkdownFlavor"
},
"default": {}
},
"code-block-tools": {
"description": "Code block tools configuration for per-language linting and formatting\nusing external tools like ruff, prettier, shellcheck, etc.",
"$ref": "#/$defs/CodeBlockToolsConfig",
"default": {
"enabled": false,
"normalize-language": "linguist",
"on-error": "fail",
"on-missing-language-definition": "ignore",
"on-missing-tool-binary": "warn",
"binary-preferences": {},
"on-missing-language-tag": "ignore",
"on-missing-mode-definition": "ignore",
"on-no-tools-run": "ignore",
"timeout": 30000,
"languages": {},
"language-aliases": {},
"tools": {}
}
}
},
"additionalProperties": {
"$ref": "#/$defs/RuleConfig"
},
"$defs": {
"GlobalConfig": {
"description": "Global configuration options",
"type": "object",
"properties": {
"enable": {
"description": "Enabled rules",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"disable": {
"description": "Disabled rules",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"exclude": {
"description": "Files to exclude. Glob patterns, relative to the project root; a\nleading `~/` expands to the home directory and absolute paths are\nmatched as written.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"include": {
"description": "Files to include. Glob patterns, relative to the project root; a\nleading `~/` expands to the home directory and absolute paths are\nmatched as written.",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"respect-gitignore": {
"description": "Respect .gitignore, .ignore and git exclude files when scanning\ndirectories. .markdownlintignore applies regardless, and explicitly\nnamed files bypass both.",
"type": "boolean",
"default": true
},
"line-length": {
"description": "Global line length setting (used by MD013 and other rules if not overridden)",
"$ref": "#/$defs/LineLength",
"default": 80
},
"output-format": {
"description": "Output format for linting results (e.g., \"text\", \"json\", \"pylint\", etc.)",
"type": [
"string",
"null"
]
},
"fixable": {
"description": "Rules that are allowed to be fixed when --fix is used\nIf specified, only these rules will be fixed",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"unfixable": {
"description": "Rules that should never be fixed, even when --fix is used\nTakes precedence over fixable",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"flavor": {
"description": "Markdown flavor/dialect to use (mkdocs, gfm, commonmark, etc.)\nWhen set, adjusts parsing and validation rules for that specific Markdown variant",
"$ref": "#/$defs/MarkdownFlavor",
"default": "standard"
},
"force-exclude": {
"description": "\\[DEPRECATED\\] Whether to enforce exclude patterns for explicitly passed paths.\nThis option is deprecated as of v0.0.156 and has no effect.\nExclude patterns are now always respected, even for explicitly provided files.\nThis prevents duplication between rumdl config and tool configs like pre-commit.",
"type": "boolean",
"deprecated": true,
"default": false
},
"cache-dir": {
"description": "Directory to store cache files (default: .rumdl_cache).\nA leading `~/` expands to the home directory; a relative path resolves\nagainst the project root.\nCan also be set via --cache-dir CLI flag or RUMDL_CACHE_DIR environment variable",
"type": [
"string",
"null"
]
},
"cache": {
"description": "Whether caching is enabled (default: true)\nCan also be disabled via --no-cache CLI flag",
"type": "boolean",
"default": true
},
"extend-enable": {
"description": "Additional rules to enable on top of the base set (additive)",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"extend-disable": {
"description": "Additional rules to disable on top of the base set (additive)",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"editorconfig": {
"description": "Whether to read settings from `.editorconfig` files (default: false).\nWhen enabled, the `.editorconfig` properties that map onto rumdl\nsettings fill in anything no rumdl config sets, resolved per file so\nsection globs and nested `.editorconfig` files apply as written.",
"type": "boolean",
"default": false
}
}
},
"LineLength": {
"description": "A line length value that can be 0 (meaning no limit) or a positive value (≥1)\n\nMany configuration values for line length need to support both:\n- 0: Special value meaning \"no line length limit\"\n- ≥1: Actual line length limit\n\nThis type enforces those constraints at deserialization time.",
"type": [
"integer",
"null"
],
"format": "uint",
"minimum": 0
},
"MarkdownFlavor": {
"description": "Markdown flavor/dialect. Accepts: standard, gfm, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, myst, hugo, mdg, gh-aw (preview). Aliases: commonmark/github map to standard, qmd/rmd/rmarkdown map to quarto, jekyll maps to kramdown, azure/ado map to azure_devops, mystmd maps to myst, goldmark maps to hugo, markdown_with_gherkin maps to mdg.",
"type": "string",
"enum": [
"standard",
"gfm",
"github",
"commonmark",
"mkdocs",
"mdx",
"pandoc",
"quarto",
"qmd",
"rmd",
"rmarkdown",
"obsidian",
"kramdown",
"jekyll",
"azure_devops",
"azure",
"ado",
"myst",
"mystmd",
"hugo",
"goldmark",
"mdg",
"markdown_with_gherkin",
"gh-aw"
]
},
"CodeBlockToolsConfig": {
"description": "Master configuration for code block tools.\n\nThis is disabled by default for safety - users must explicitly enable it.",
"type": "object",
"properties": {
"enabled": {
"description": "Master switch (default: false)",
"type": "boolean",
"default": false
},
"normalize-language": {
"description": "Language normalization strategy",
"$ref": "#/$defs/NormalizeLanguage",
"default": "linguist"
},
"on-error": {
"description": "Global error handling strategy",
"$ref": "#/$defs/OnError",
"default": "fail"
},
"on-missing-language-definition": {
"description": "Behavior when a recognized language has no tools configured in either mode.",
"$ref": "#/$defs/OnMissing",
"default": "ignore"
},
"on-missing-tool-binary": {
"description": "Behavior when a configured tool's binary is absent from the allowed lookup locations.\nDefaults to `warn`: the tools rumdl drives are installed separately from\nrumdl, so an absent one is common enough that silence about it is a trap.",
"$ref": "#/$defs/OnMissing",
"default": "warn"
},
"binary-preferences": {
"description": "Select already-installed project/PATH executables per underlying binary.",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/BinaryPreference"
},
"default": {}
},
"on-missing-language-tag": {
"description": "Policy for unlabeled fenced code blocks.",
"$ref": "#/$defs/OnMissing",
"default": "ignore"
},
"on-unknown-language-tag": {
"description": "Policy for unknown tags. When omitted, inherits on-missing-language-definition.",
"anyOf": [
{
"$ref": "#/$defs/OnMissing"
},
{
"type": "null"
}
]
},
"on-missing-mode-definition": {
"description": "Policy for a configured language missing tools for the active mode.",
"$ref": "#/$defs/OnMissing",
"default": "ignore"
},
"on-no-tools-run": {
"description": "Invocation-level policy when no tool or valid cached tool check was used.",
"$ref": "#/$defs/OnMissing",
"default": "ignore"
},
"timeout": {
"description": "Timeout per tool execution in milliseconds (default: 30000)",
"type": "integer",
"minimum": 0,
"default": 30000
},
"languages": {
"description": "Per-language tool configuration",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/LanguageToolConfig"
},
"default": {}
},
"language-aliases": {
"description": "User-defined language aliases (override built-in resolution)\nExample: { \"py\": \"python\", \"bash\": \"shell\" }",
"type": "object",
"additionalProperties": {
"type": "string"
},
"default": {}
},
"tools": {
"description": "Custom tool definitions (override built-ins)",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/ToolDefinition"
},
"default": {}
}
}
},
"NormalizeLanguage": {
"description": "Language normalization strategy.",
"oneOf": [
{
"description": "Resolve language aliases using GitHub Linguist data (e.g., \"py\" -> \"python\")",
"type": "string",
"const": "linguist"
},
{
"description": "Use the language tag exactly as written in the code block",
"type": "string",
"const": "exact"
}
]
},
"OnError": {
"description": "Error handling strategy for tool execution failures.",
"oneOf": [
{
"description": "Fail the lint/format operation (propagate error)",
"type": "string",
"const": "fail"
},
{
"description": "Continue with the next tool without a warning",
"type": "string",
"const": "skip"
},
{
"description": "Log a warning but continue processing",
"type": "string",
"const": "warn"
}
]
},
"OnMissing": {
"description": "Behavior when a configured coverage or availability condition is unmet.",
"oneOf": [
{
"description": "Silently skip and continue processing",
"type": "string",
"const": "ignore"
},
{
"description": "Emit one configuration warning per condition, then continue.\n`--deny-config-warnings` makes the warning fatal.",
"type": "string",
"const": "warn"
},
{
"description": "Report an error and continue; invocation conditions use exit code 2.",
"type": "string",
"const": "fail"
},
{
"description": "Stop immediately on the first occurrence, exit non-zero",
"type": "string",
"const": "fail-fast"
}
]
},
"BinaryPreference": {
"description": "Preference for resolving an external executable. Explicit paths bypass this.",
"oneOf": [
{
"description": "Prefer the project's virtual environment or node_modules, then PATH.",
"type": "string",
"const": "project"
},
{
"description": "Prefer PATH, then project-local installations.",
"type": "string",
"const": "system"
},
{
"description": "Require a project-local installation.",
"type": "string",
"const": "only-project"
},
{
"description": "Preserve PATH-only lookup.",
"type": "string",
"const": "only-system"
}
]
},
"LanguageToolConfig": {
"description": "Per-language tool configuration.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether code block tools are enabled for this language (default: true).\nSet to false to acknowledge a language without configuring tools.\nThis satisfies strict mode (on-missing-language-definition) checks.",
"type": "boolean",
"default": true
},
"lint": {
"description": "Tools to run in lint mode (rumdl check)",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"format": {
"description": "Tools to run in format mode (rumdl check --fix / rumdl fmt)",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"format-mode": {
"description": "How the `format` list is applied: as fallbacks (default) or as a pipeline",
"$ref": "#/$defs/FormatMode",
"default": "fallback"
},
"on-error": {
"description": "Override global on-error setting for this language",
"anyOf": [
{
"$ref": "#/$defs/OnError"
},
{
"type": "null"
}
],
"default": null
}
}
},
"FormatMode": {
"description": "How a language's `format` list is applied to a code block.",
"oneOf": [
{
"description": "Try the formatters in order; the first one that succeeds supplies the\nblock, even when it changes nothing",
"type": "string",
"const": "fallback"
},
{
"description": "Run every formatter in order, each on the output of the last one that\nsucceeded, and replace the block with the final result",
"type": "string",
"const": "pipeline"
}
]
},
"ToolDefinition": {
"description": "Definition of an external tool.\n\nThis describes how to invoke a tool and how it communicates.",
"type": "object",
"properties": {
"command": {
"description": "Command to run (first element is the binary, rest are arguments)",
"type": "array",
"items": {
"type": "string"
}
},
"stdin": {
"description": "Whether the tool reads from stdin (default: true)",
"type": "boolean",
"default": true
},
"stdout": {
"description": "Whether the tool writes to stdout (default: true)",
"type": "boolean",
"default": true
},
"lint-args": {
"description": "Additional arguments for lint mode (appended to command)",
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"format-args": {
"description": "Additional arguments for format mode (appended to command)",
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": [
"command"
]
},
"RuleConfig": {
"description": "Represents a rule-specific configuration",
"type": "object",
"properties": {
"severity": {
"description": "Severity override for this rule (Error, Warning, or Info)",
"anyOf": [
{
"$ref": "#/$defs/Severity"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
"Severity": {
"type": "string",
"enum": [
"error",
"warning",
"info"
]
}
}
}