feat: use the new plugin options group

Author: KyleKing

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
       - id: trailing-whitespace
         exclude: __snapshots__/.*\.ambr
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.18
+    rev: 0.7.19
     hooks:
       - id: mdformat
         additional_dependencies:

README.md

@@ -49,7 +49,7 @@ Add this package wherever you use `mdformat` and the plugin will be auto-recogni
 ```yaml
 repos:
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.18
+    rev: 0.7.19
     hooks:
       - id: mdformat
         additional_dependencies:
@@ -105,21 +105,33 @@ md.render(text)
 # </ul>
 ```
 
-## CLI Options
+## Configuration
 
-`mdformat-mkdocs` adds the CLI argument `--align-semantic-breaks-in-lists` to optionally align line breaks in numbered lists to 3-spaces. If not specified, the default of 4-indents is followed universally.
+`mdformat-mkdocs` adds the CLI arguments:
 
-```txt
-# with: mdformat
-1. Semantic line feed where the following line is
-    three spaces deep
+- `--align-semantic-breaks-in-lists` to optionally align line breaks in numbered lists to 3-spaces. If not specified, the default of 4-indents is followed universally.
 
-# vs. with: mdformat --align-semantic-breaks-in-lists
-1. Semantic line feed where the following line is
-   three spaces deep
-```
+    ```txt
+    # with: mdformat
+    1. Semantic line feed where the following line is
+        three spaces deep
+
+    # vs. "mdformat --align-semantic-breaks-in-lists"
+    1. Semantic line feed where the following line is
+       three spaces deep
+    ```
+
+- `--ignore-missing-references` if set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings
 
-Note: the `align-semantic-breaks-in-lists` setting is not supported in the configuration file yet (https://github.com/executablebooks/mdformat/issues/378)
+You can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):
+
+```toml
+# .mdformat.toml
+
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true
+ignore_missing_references = true
+```
 
 ## Contributing
 

mdformat_mkdocs/__init__.py

@@ -2,8 +2,10 @@
 
 __version__ = "4.1.0"
 
+__plugin_name__ = "mkdocs"
+
 # FYI see source code for available interfaces:
 #   https://github.com/executablebooks/mdformat/blob/5d9b573ce33bae219087984dd148894c774f41d4/src/mdformat/plugins.py
-from .plugin import POSTPROCESSORS, RENDERERS, add_cli_options, update_mdit
+from .plugin import POSTPROCESSORS, RENDERERS, add_cli_argument_group, update_mdit
 
-__all__ = ("POSTPROCESSORS", "RENDERERS", "add_cli_options", "update_mdit")
+__all__ = ("POSTPROCESSORS", "RENDERERS", "add_cli_argument_group", "update_mdit")

mdformat_mkdocs/_helpers.py

@@ -3,8 +3,11 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Mapping
 from functools import wraps
-from typing import Callable
+from typing import Any, Callable
+
+from . import __plugin_name__
 
 EOL = "\n"
 """Line delimiter."""
@@ -42,3 +45,16 @@ def separate_indent(line: str) -> tuple[str, str]:
     match = re_indent.match(line)
     assert match  # for pyright
     return (match["indent"], match["content"])
+
+
+ContextOptions = Mapping[str, Any]
+
+
+def get_conf(options: ContextOptions, key: str) -> bool | str | int | None:
+    """Read setting from mdformat configuration Context."""
+    cli_or_toml = (
+        options["mdformat"].get("plugin", {}).get(__plugin_name__, {}).get(key)
+    )
+    if cli_or_toml is None:
+        return options["mdformat"].get(key)  # From API
+    return cli_or_toml

mdformat_mkdocs/_normalize_list.py

@@ -16,6 +16,7 @@
     EOL,
     FILLER_CHAR,
     MKDOCS_INDENT_COUNT,
+    get_conf,
     rstrip_result,
     separate_indent,
 )
@@ -469,7 +470,7 @@ def normalize_list(
         return text
 
     # Retrieve user-options
-    inc_numbers = bool(context.options["mdformat"].get("number"))
+    inc_numbers = bool(get_conf(context.options, "number"))
 
     parsed_text = parse_text(
         text=text,

mdformat_mkdocs/_postprocess_inline.py

@@ -4,7 +4,7 @@
 
 from mdformat.renderer import RenderContext, RenderTreeNode
 
-from ._helpers import FILLER_CHAR, MKDOCS_INDENT_COUNT, rstrip_result
+from ._helpers import FILLER_CHAR, MKDOCS_INDENT_COUNT, get_conf, rstrip_result
 
 FILLER = FILLER_CHAR * (MKDOCS_INDENT_COUNT - 2)  # `mdformat` default is two spaces
 """A spacer that is inserted and then removed to ensure proper word wrap."""
@@ -28,7 +28,7 @@ def postprocess_list_wrap(
     """
     if not context.do_wrap:
         return text
-    wrap_mode = context.options["mdformat"]["wrap"]
+    wrap_mode = get_conf(context.options, "wrap")
     if (
         not isinstance(wrap_mode, int)  # noqa: PLR0916
         or FILLER_CHAR in text

mdformat_mkdocs/plugin.py

@@ -2,16 +2,16 @@
 
 from __future__ import annotations
 
+import argparse
 import textwrap
-from argparse import ArgumentParser
 from collections.abc import Mapping
 from functools import partial
-from typing import Any
 
 from markdown_it import MarkdownIt
 from mdformat.renderer import DEFAULT_RENDERERS, RenderContext, RenderTreeNode
 from mdformat.renderer.typing import Postprocess, Render
 
+from ._helpers import ContextOptions, get_conf
 from ._normalize_list import normalize_list as unbounded_normalize_list
 from ._postprocess_inline import postprocess_list_wrap
 from .mdit_plugins import (
@@ -29,16 +29,14 @@
     pymd_snippet_plugin,
 )
 
-ContextOptions = Mapping[str, Any]
-
 
 def cli_is_ignore_missing_references(options: ContextOptions) -> bool:
     """user-specified flag to turn off bracket escaping when no link reference found.
 
     Addresses: https://github.com/KyleKing/mdformat-mkdocs/issues/19
 
     """
-    return options["mdformat"].get("ignore_missing_references", False)
+    return bool(get_conf(options, "ignore_missing_references")) or False
 
 
 def cli_is_align_semantic_breaks_in_lists(options: ContextOptions) -> bool:
@@ -48,17 +46,21 @@ def cli_is_align_semantic_breaks_in_lists(options: ContextOptions) -> bool:
     - and 2-spaces on subsequent bulleted items
 
     """
-    return options["mdformat"].get("align_semantic_breaks_in_lists", False)
+    return bool(get_conf(options, "align_semantic_breaks_in_lists")) or False
+
 
+def add_cli_argument_group(group: argparse._ArgumentGroup) -> None:
+    """Add options to the mdformat CLI.
 
-def add_cli_options(parser: ArgumentParser) -> None:
-    """Add options to the mdformat CLI, to be stored in `mdit.options["mdformat"]`."""
-    parser.add_argument(
+    Stored in `mdit.options["mdformat"]["plugin"]["tables"]`
+
+    """
+    group.add_argument(
         "--align-semantic-breaks-in-lists",
         action="store_true",
         help="If specified, align semantic indents in numbered and bulleted lists to the text",  # noqa: E501
     )
-    parser.add_argument(
+    group.add_argument(
         "--ignore-missing-references",
         action="store_true",
         help="If set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings",  # noqa: E501
@@ -187,7 +189,7 @@ def add_extra_admon_newline(node: RenderTreeNode, context: RenderContext) -> str
 
 
 normalize_list = partial(
-    unbounded_normalize_list,
+    unbounded_normalize_list,  # type: ignore[has-type]
     check_if_align_semantic_breaks_in_lists=cli_is_align_semantic_breaks_in_lists,
 )
 
@@ -198,6 +200,6 @@ def add_extra_admon_newline(node: RenderTreeNode, context: RenderContext) -> str
 # will run in series.
 POSTPROCESSORS: Mapping[str, Postprocess] = {
     "bullet_list": normalize_list,
-    "inline": postprocess_list_wrap,
+    "inline": postprocess_list_wrap,  # type: ignore[has-type]
     "ordered_list": normalize_list,
 }