Skip to content

flavors.md

Latest commit

 

History

History
85 lines (62 loc) · 4.79 KB

flavors.md

File metadata and controls

85 lines (62 loc) · 4.79 KB

Markdown Flavors

rumdl supports multiple Markdown flavors to accommodate different documentation systems. Each flavor adjusts specific rule behavior where that system differs from standard Markdown.

Quick Reference

Flavor Use Case Rules Affected
standard Default Markdown with GFM extensions Baseline behavior
gfm GitHub Flavored Markdown MD033, MD034
mkdocs MkDocs / Material for MkDocs MD024, MD031, MD033, MD038, MD040, MD042, MD046, MD049, MD050, MD052, MD056
mdx MDX (JSX in Markdown) MD013, MD033, MD037, MD039, MD044, MD049
obsidian Obsidian knowledge base MD011, MD012, MD018, MD028, MD033, MD034, MD037, MD038, MD044, MD049, MD061, MD064, MD069
pandoc Pandoc Markdown MD022, MD029, MD031, MD032, MD034, MD037, MD040, MD042, MD051, MD052
quarto Quarto / RMarkdown MD022, MD029, MD031, MD032, MD034, MD037, MD038, MD040, MD042, MD049, MD050, MD051, MD052
kramdown Jekyll / kramdown MD022, MD041, MD051
azure_devops Azure DevOps wikis MD013, MD031, MD034, MD046, MD048

Configuration

Global Flavor

Set the default flavor for all files:

[global]
flavor = "mkdocs"

Per-File Flavor

Override flavor for specific file patterns:

[per-file-flavor]
"docs/**/*.md" = "mkdocs"
"**/*.mdx" = "mdx"
"**/*.qmd" = "quarto"

Auto-Detection

When no flavor is configured, rumdl auto-detects based on file extension:

Extension Detected Flavor
.mdx mdx
.qmd, .Rmd quarto
.kramdown kramdown
.md, .markdown standard

Specification Versions

rumdl uses pulldown-cmark for Markdown parsing, which implements CommonMark 0.31.2 (January 2024).

The standard flavor includes CommonMark plus widely-adopted GFM extensions (tables, task lists, strikethrough, autolinks). Other flavors build on this baseline with additional syntax support.

Flavor Details

  • Standard - CommonMark 0.31.2 + GFM extensions (tables, task lists, strikethrough, autolinks)
  • GFM - GitHub-specific features: security-sensitive HTML warnings, extended autolinks
  • MkDocs - Admonitions, content tabs, autorefs, mkdocstrings, extended syntax
  • MDX - JSX components, JSX attributes, expressions, ESM imports
  • Obsidian - Callouts, comments, highlights, Dataview queries, Templater syntax, tags
  • Pandoc - Fenced divs, attribute lists, citations, footnotes, definition lists, math, raw format blocks, grid/multi-line tables, line blocks, sub/superscripts, example lists
  • Quarto - Citations, shortcodes, div blocks, math blocks, executable code
  • Kramdown - IALs, ALDs, extension blocks, kramdown anchor generation
  • Azure DevOps - Colon code fences (:::mermaid … :::) treated as opaque code blocks

Adding Flavor Support

If you encounter a pattern that rumdl doesn't handle correctly for your documentation system:

  1. Check if the pattern is already supported in the flavor documentation
  2. Try configuring the relevant rule to allow the pattern
  3. Open an issue with:
    • The Markdown content that triggers a false positive
    • The documentation system and version you're using
    • The expected behavior

See Also