.markdownlint.yaml

# SPDX-License-Identifier: Apache-2.0
#
# Copyright 2023-2024 The Enola <https://enola.dev> Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# https://github.com/DavidAnson/markdownlint#optionsconfig
# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml

default: true

MD007:
  indent: 6
  start_indented: false
  # start_indent: 2

MD013:
  # Must match .editorconfig [*.md] max_line_length
  # This 4096 means "unlimited" (unset) - essentially https://github.com/DavidAnson/markdownlint/issues/298.
  # Until https://github.com/DavidAnson/markdownlint/issues/535 is available,
  # it's not feasible to set this - just too PITA, while writing docs.
  #
  # One possible avenue to enable fixing automatic reflow formatting could be
  # to enable Prettier to format MD (by removing *.md from .prettierignore).
  # This ALMOST works, but in Prettier v2.8.4 just has some issues:
  #   A. Breaks code blocks inside 1. 1. 1. OL; see https://github.com/prettier/prettier/issues/13175
  #   B. Replaces '*' with '-' for UL; not my preference, but is likely intentional,
  #      given https://prettier.io/docs/en/option-philosophy.html.
  #   C. It over-indents '-' causing MD030; see https://github.com/prettier/prettier/issues/5299
  #      and https://github.com/prettier/prettier/pull/5306 or https://github.com/prettier/prettier/pull/13987 ?
  # Another avenue would be to look into a different MD formatter than Prettier,
  # perhaps remark directly ... but that seems a bit overkill, for now.
  line_length: 4096
  code_blocks: true
  code_block_line_length: 4096
  strict: false
  stern: false

# Allow headings ending in '!'
MD026:
  punctuation: ",;:。，；："

# Allow <sub> but no other inline HTML in source MD
MD033:
  allowed_elements:
    - "sub"

# Bare URL are OK
MD034: false

# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md046---code-block-style
# style: "indented" prevents setting code block language
# style: "fenced" enforces ``` and thus prevents indenting, which is nicer to read in raw ASCII where possible
# style: "consistent" prevents mixing indenting (without code block language) and fenced with code block language.
MD046: false