chore: add configuration files for mdformat and markdownlint

Add .mdformat.toml and .markdownlint.yaml to configure formatting and linting rules for Markdown files. These configurations ensure compatibility with MkDocs and enforce consistent styling across the documentation.

Author: Mdevpro78

.markdownlint.yaml

@@ -0,0 +1,177 @@
+# MkDocs-compatible markdownlint configuration
+
+# Default state for all rules
+default: true
+
+# Path to configuration file to extend
+extends: null
+
+# MD001/heading-increment : Heading levels should only increment by one level at a time
+MD001: true
+
+# MD003/heading-style : Heading style
+MD003:
+  # Use ATX style headings for MkDocs
+  style: "atx"
+
+# MD004/ul-style : Unordered list style
+MD004:
+  # MkDocs works best with dash style
+  style: "dash"
+
+# MD005/list-indent : Inconsistent indentation for list items at the same level
+MD005: true
+
+# MD007/ul-indent : Unordered list indentation
+MD007:
+  # Standard 4 space indent works better with MkDocs
+  indent: 4
+  start_indented: false
+  start_indent: 4
+
+# MD009/no-trailing-spaces : Trailing spaces
+MD009:
+  # Allow line breaks in MkDocs content
+  br_spaces: 2
+  list_item_empty_lines: true
+  strict: false
+
+# MD010/no-hard-tabs : Hard tabs
+MD010:
+  code_blocks: true
+  # Allow tabs in some code languages
+  ignore_code_languages: [
+    "makefile", "Makefile", "python",
+    "yaml", "yml", "sh", "bash", "markdown",
+    "md", "toml", "ini", "toml",
+    "json", "dockerfile", "toml",
+    "plaintext", "text", "txt", "shell",
+    "console", "mermaid", "plantuml",
+    "puml", "ps1", "powershell"
+  ]
+  spaces_per_tab: 4
+
+# MD011/no-reversed-links : Reversed link syntax
+MD011: true
+
+# MD012/no-multiple-blanks : Multiple consecutive blank lines
+MD012: false,  # 🚫 Allow multiple consecutive blank lines
+
+# MD013/line-length : Line length
+MD013: false # 🚫 Disable line length restrictions (similar to mdformat --wrap=no)
+
+# MD014/commands-show-output : Dollar signs used before commands without showing output
+MD014: true
+
+# MD018-MD023: Heading formatting rules
+MD018: true
+MD019: true
+MD020: true
+MD021: true
+MD022: true
+MD023: false  # Allow indented headings for MkDocs features
+
+# MD024/no-duplicate-heading : Multiple headings with the same content
+MD024:
+  # Allow same headings in different sections (common in MkDocs)
+  siblings_only: true
+
+# MD025/single-title/single-h1 : Multiple top-level headings
+MD025:
+  # Configure for MkDocs frontmatter
+  level: 1
+  front_matter_title: "^\\s*(title|page.title)\\s*[:=]"
+
+# MD026/no-trailing-punctuation : Trailing punctuation in heading
+MD026:
+  # Allow question marks in headings
+  punctuation: ".,;:!。，；：！"
+
+# MD027-MD030: Spacing and style rules
+MD027: true
+MD028: false  # Allow blank lines in blockquotes for MkDocs styling
+MD029:
+  style: "one_or_ordered"
+MD030: true
+
+# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines
+MD031:
+  list_items: true
+
+# MD032/blanks-around-lists : Lists should be surrounded by blank lines
+MD032: true
+
+# MD033/no-inline-html : Inline HTML
+MD033: false  # Disable inline HTML restriction completely for MkDocs templates
+
+# MD034/no-bare-urls : Bare URL used
+MD034: true
+
+# MD035/hr-style : Horizontal rule style
+MD035:
+  style: "---"  # MkDocs standard
+
+# MD036/no-emphasis-as-heading : Emphasis used instead of a heading
+MD036:
+  punctuation: ".,;:!?。，；：！？"
+
+# MD037-MD039: Emphasis and links formatting
+MD037: true
+MD038: true
+MD039: true
+
+# MD040/fenced-code-language : Fenced code blocks should have a language specified
+MD040: false # 🚫 Allow non-fenced code blocks (if needed)
+
+# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading
+MD041: false  # Disable requirement for first line to be heading for MkDocs templates
+
+# MD042/no-empty-links : No empty links
+MD042: false  # Allow placeholder links used in MkDocs templates
+
+# MD043/required-headings : Required heading structure
+MD043: false
+
+
+# MD044/proper-names : Proper names should have the correct capitalization
+MD044: false  # Disable proper names capitalization check for flexibility
+
+# MD045/no-alt-text : Images should have alternate text (alt text)
+MD045: true
+
+# MD046/code-block-style : Code block style
+MD046: false
+
+# MD047/single-trailing-newline : Files should end with a single newline character
+MD047: true
+
+# MD048/code-fence-style : Code fence style
+MD048:
+  # Triple backticks are standard in MkDocs
+  style: "backtick"
+
+# MD049/emphasis-style : Emphasis style
+MD049:
+  style: "asterisk"  # Standard for MkDocs
+
+# MD050/strong-style : Strong style
+MD050:
+  style: "asterisk"  # Standard for MkDocs
+
+# MD051-MD058: Link and table formatting
+MD051: false  # Disable link fragment checking for MkDocs compatibility
+MD052: true
+MD053:
+  ignored_definitions: ["//", "#"]  # Allow MkDocs-specific reference formats
+MD054:
+  # Allow all link styles for maximum compatibility
+  autolink: true
+  inline: true
+  full: true
+  collapsed: true
+  shortcut: true
+  url_inline: true
+MD055:
+  style: "consistent"
+MD056: true
+MD058: true

.mdformat.toml

@@ -0,0 +1,36 @@
+
+# MDFormat configuration for MkDocs compatibility
+
+# Top-level configuration (don't use 'mdformat' section)
+wrap = "no"
+number = true
+end_of_line = "lf"
+validate = true
+
+# Plugin configuration
+plugin.gfm.enable = true
+plugin.frontmatter.enable = true
+plugin.mkdocs.enable = true
+plugin.mkdocs.align_semantic_breaks_in_lists = true
+plugin.mkdocs.ignore_missing_references = true
+plugin.footnote.enable = true
+plugin.tables.enable = true
+plugin.toc.enable = true
+plugin.toc.depth = 4
+plugin.myst.enable = true
+plugin.gfm_alerts.enable = true
+plugin.config.enable = true
+plugin.simple_breaks.enable = true
+plugin.web.enable = true
+
+# Code formatter plugins
+plugin.beautysh.enable = true
+plugin.beautysh.indent_size = 4
+
+plugin.black.enable = true
+plugin.black.line_length = 88
+
+plugin.ruff.enable = true
+plugin.ruff.line_length = 88
+plugin.ruff.select = ["E", "F", "W"]
+plugin.ruff.ignore = ["ANN101"]