Configurable breaks

.mdformat.toml

@@ -0,0 +1,5 @@
+wrap = 99                        # possible values: {"keep", "no", INTEGER}
+number = true                    # possible values: {false, true}
+end_of_line = "lf"               # possible values: {"lf", "crlf", "keep"}
+thematic_breaks_character = "-"  # possible values: {"-", "_", "*"}
+thematic_breaks_length = 3       # possible values: 3 <= INTEGER

README.md

@@ -1,20 +1,9 @@
 # mdformat-simple-breaks
 
-[![Build Status][ci-badge]][ci-link]
-[![codecov.io][cov-badge]][cov-link]
+[![Build Status][ci-badge]][ci-link] [![codecov.io][cov-badge]][cov-link]
 [![PyPI version][pypi-badge]][pypi-link]
 
-An [mdformat][mdformat] plugin to render *thematic breaks* using three dashes
-
-```
----
-```
-
-instead of 70 underscores
-
-```
-________________________________________________________________________________
-```
+An [mdformat] plugin to make thematic breaks rendering style configurable.
 
 ## Install
 
@@ -24,6 +13,8 @@ Install with:
 pip install mdformat-simple-breaks
 ```
 
+After the installation, the plugin will be automatically used when running `mdformat` as usual.
+
 ## Usage as a [pre-commit](https://pre-commit.com) hook
 
 Add the following to your `.pre-commit-config.yaml`:
@@ -37,6 +28,28 @@ Add the following to your `.pre-commit-config.yaml`:
         - mdformat-simple-breaks
 ```
 
+## Configuration
+
+### CLI Arguments
+
+By default this plugin will render the thematic breaks as a line made of three dashes `---`, but
+this can be modified by using the following command line options when running `mdformat`:
+
+- `--thematic-breaks-character`: Character to use when rendering the thematic breaks. Possible
+  values are `-` (default), `_` and `*`.
+- `--thematic-breaks-length`: Number of times that the character will be repeated to render the
+  thematic break. Only integer values greater than 2 are accepted. Default is 3.
+
+### `.mdformat.toml`
+
+If an [`.mdformat.toml`][mdformat-toml] file is used to pass options to `mdformat`, the following two lines can be
+added to configure the `mdformat-simple-breaks` plugin:
+
+```
+thematic_breaks_character = "-"  # possible values: {"-", "_", "*"}
+thematic_breaks_length = 3       # possible values: INTEGER greater than 2
+```
+
 ## Plugin rationale
 
 The [CommonMark specification][commonmark-spec] states that *thematic breaks*, which are to be
@@ -50,21 +63,21 @@ As a result, most of the Markdown guides and cheat sheets show a line made of th
 as an example of a *thematic break*, and therefore this likely to be the format which Markdown
 writers are most used to type.
 
-On the other hand, plain [mdformat][mdformat] renders these *thematic breaks* [as a line of 70
+On the other hand, plain [mdformat] renders these *thematic breaks* [as a line of 70
 consecutive underscore characters][mdformat-thematic-breaks]. This is an [explicit style decision
 ][style-change] that is not going to be reverted and for which no configuration will be added.
 
-As a result, this plugin has been created to offer the option to render the *thematic breaks*
-using the common three dash style when preferred.
-
+As a result, this plugin has been created to offer the option to render the *thematic breaks* using
+any style preferred by the user.
 
 [ci-badge]: https://github.com/csala/mdformat-simple-breaks/workflows/CI/badge.svg?branch=master
 [ci-link]: https://github.com/csala/mdformat/actions?query=workflow%3ACI+branch%3Amaster+event%3Apush
-[cov-badge]: https://codecov.io/gh/csala/mdformat-simple-breaks/branch/master/graph/badge.svg
-[cov-link]: https://codecov.io/gh/csala/mdformat-simple-breaks
-[pypi-badge]: https://img.shields.io/pypi/v/mdformat-simple-breaks.svg
-[pypi-link]: https://pypi.org/project/mdformat-simple-breaks
-[mdformat]: https://github.com/executablebooks/mdformat
 [commonmark-spec]: https://spec.commonmark.org/0.30/#thematic-breaks
-[style-change]: https://github.com/executablebooks/mdformat/issues/69
+[cov-badge]: https://codecov.io/gh/csala/mdformat-thematic-breaks/branch/master/graph/badge.svg
+[cov-link]: https://codecov.io/gh/csala/mdformat-thematic-breaks
+[mdformat]: https://github.com/executablebooks/mdformat
 [mdformat-thematic-breaks]: https://mdformat.readthedocs.io/en/stable/users/style.html#thematic-breaks
+[mdformat-toml]: https://mdformat.readthedocs.io/en/stable/users/configuration_file.html
+[pypi-badge]: https://img.shields.io/pypi/v/mdformat-thematic-breaks.svg
+[pypi-link]: https://pypi.org/project/mdformat-thematic-breaks
+[style-change]: https://github.com/executablebooks/mdformat/issues/69

mdformat_simple_breaks/__init__.py

@@ -2,4 +2,4 @@
 
 __version__ = "0.0.1"
 
-from .plugin import RENDERERS, update_mdit  # noqa: F401
+from .plugin import RENDERERS, add_cli_options, update_mdit  # noqa: F401

mdformat_simple_breaks/plugin.py

@@ -1,19 +1,77 @@
 """Main plugin module."""
 
+import argparse
+from pathlib import Path
 from typing import Mapping
 
 from markdown_it import MarkdownIt
+from mdformat import _conf
 from mdformat.renderer import RenderContext, RenderTreeNode
 from mdformat.renderer.typing import Render
 
+_conf_validate_values = _conf._validate_values
+
+
+def _validate_values(opts: Mapping, conf_path: Path) -> None:
+    _conf_validate_values(opts, conf_path)
+    wrap = opts.get("wrap")
+    if not isinstance(wrap, int):
+        wrap = 70
+
+    character = opts.get("thematic_breaks_character")
+    if character not in (None, "-", "_", "*"):
+        raise _conf.InvalidConfError(
+            f"Invalid 'thematic_breaks_character' value in {conf_path}: {character}"
+        )
+
+    length = opts.get("thematic_breaks_length")
+    if length is not None and not (isinstance(length, int) and 3 <= length <= wrap):
+        raise _conf.InvalidConfError(
+            f"Invalid 'thematic_breaks_length' value in {conf_path}: {length}"
+        )
+
+
+def _monkey_patch_mdformat_on_import() -> None:
+    """Monkey patch the mdformat._conf to add the plugin opts.`"""
+    _conf.DEFAULT_OPTS["thematic_breaks_character"] = "-"
+    _conf.DEFAULT_OPTS["thematic_breaks_length"] = 3
+    _conf._validate_values = _validate_values
+
+
+def thematic_break_length(value: str) -> int:
+    value = int(value)
+    if value < 3:
+        raise ValueError("thematic_break_length must be an integer greater than 2")
+
+    return value
+
+
+def add_cli_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--thematic-breaks-character",
+        choices=("-", "_", "*"),
+        help="Character to use for rendering thematic breaks (default: -)",
+    )
+    parser.add_argument(
+        "--thematic-breaks-length",
+        type=thematic_break_length,
+        help="Length of the rendered thematic breaks (default: 3)",
+    )
+
 
 def update_mdit(mdit: MarkdownIt) -> None:
-    """Update the parser, e.g. by adding a plugin: `mdit.use(myplugin)`"""
+    """No-op update_mdit for mdformat-simple-breaks plugin."""
     pass
 
 
 def hr(node: RenderTreeNode, context: RenderContext) -> str:
-    return "---"
+    options = context.options["mdformat"]
+    character = options.get("thematic_breaks_character", "-")
+    length = options.get("thematic_breaks_length", 3)
+    return character * length
 
 
 RENDERERS: Mapping[str, Render] = {"hr": hr}
+
+
+_monkey_patch_mdformat_on_import()