feat: allow specifying mdformat extensions via config and CLI

Add `mdformat_extensions` option to ConfigDict and expose it through
the CLI (`--mdformat-extensions`). This lets users enable mdformat
plugins like `mdformat-tables`, which properly preserves escaped pipes
in table cells and fixes broken tabular rendering for union type hints.

Closes #23, fixes #22

Made-with: Cursor

Author: deven367

src/griffe2md/_internal/cli.py

@@ -38,6 +38,12 @@ def get_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="griffe2md")
     parser.add_argument("package", help="The package to output Markdown docs for.")
     parser.add_argument("-o", "--output", default=None, help="File to write to. Default: stdout.")
+    parser.add_argument(
+        "--mdformat-extensions",
+        nargs="*",
+        default=[],
+        help="mdformat extensions to enable (e.g. 'tables'). Requires the corresponding mdformat plugin to be installed.",
+    )
     parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
     parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
     return parser
@@ -56,7 +62,10 @@ def main(args: list[str] | None = None) -> int:
     """
     parser = get_parser()
     opts = parser.parse_args(args=args)
-    config = load_config()
+    config = load_config() or {}
+
+    if opts.mdformat_extensions:
+        config["mdformat_extensions"] = opts.mdformat_extensions
 
     write_package_docs(opts.package, config, opts.output)
     return 0

src/griffe2md/_internal/config.py

@@ -103,6 +103,13 @@ class ConfigDict(TypedDict):
     load_external_modules: bool
     """Whether to always load external modules/packages."""
 
+    mdformat_extensions: list[str]
+    """A list of mdformat extensions to enable when formatting Markdown output.
+
+    For example, `["tables"]` to enable the `mdformat-tables` extension,
+    which properly handles escaped pipes in table cells.
+    """
+
     members: list[str] | bool | None
     """A boolean, or an explicit list of members to render.
 
@@ -265,6 +272,7 @@ class ConfigDict(TypedDict):
     "show_docstring_functions": True,
     "show_docstring_modules": True,
     "extensions": [],
+    "mdformat_extensions": [],
     "search_paths": [],
 }
 """Default configuration values."""

src/griffe2md/_internal/main.py

@@ -137,7 +137,9 @@ def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_
     context = prepare_context(obj, config)
     rendered = env.get_template(f"{obj.kind.value}.md.jinja").render(**context)
     if format_md:
-        rendered = mdformat.text(rendered)
+        full_config = cast("ConfigDict", {**default_config, **(config or {})})
+        mdformat_ext = full_config.get("mdformat_extensions", [])
+        rendered = mdformat.text(rendered, extensions=mdformat_ext)
     return rendered
 
 

src/griffe2md/templates/docstring/attributes.md.jinja

@@ -5,7 +5,7 @@
 Name | Type | Description
 ---- | ---- | -----------
 {%- for attribute in section.value %}
-[`{{ attribute.name }}`](#{{ obj.path }}.{{ attribute.name }}) | {% if attribute.annotation -%}{%- with expression = attribute.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ attribute.description|newline_to_br }}
+[`{{ attribute.name }}`](#{{ obj.path }}.{{ attribute.name }}) | {% if attribute.annotation -%}{%- with expression = attribute.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ attribute.description|newline_to_br }}
 {%- endfor -%}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/other_parameters.md.jinja

@@ -5,7 +5,7 @@
 Name | Type | Description
 ---- | ---- | -----------
 {%- for parameter in section.value %}
-`{{ parameter.name }}` | {% if parameter.annotation -%}{%- with expression = parameter.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ parameter.description|newline_to_br }}
+`{{ parameter.name }}` | {% if parameter.annotation -%}{%- with expression = parameter.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ parameter.description|newline_to_br }}
 {%- endfor -%}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/parameters.md.jinja

@@ -5,7 +5,7 @@
 Name | Type | Description | Default
 ---- | ---- | ----------- | -------
 {%- for parameter in section.value %}
-`{{ parameter.name }}` | {% if parameter.annotation -%}{%- with expression = parameter.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ parameter.description|newline_to_br }} | {% if parameter.default -%}{%- with expression = parameter.default -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- else -%}*required*{%- endif %}
+`{{ parameter.name }}` | {% if parameter.annotation -%}{%- with expression = parameter.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ parameter.description|newline_to_br }} | {% if parameter.default -%}{%- with expression = parameter.default -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- else -%}*required*{%- endif %}
 {%- endfor -%}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/raises.md.jinja

@@ -5,7 +5,7 @@
 Type | Description
 ---- | -----------
 {% for raises in section.value %}
-{%- if raises.annotation -%}{%- with expression = raises.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif -%} | {{ raises.description|newline_to_br }}
+{%- if raises.annotation -%}{%- with expression = raises.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif -%} | {{ raises.description|newline_to_br }}
 {% endfor %}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/receives.md.jinja

@@ -6,7 +6,7 @@
 {% if name_column -%}Name | {% endif -%}Type | Description
 {% if name_column -%}---- | {% endif -%}---- | -----------
 {% for receives in section.value %}
-{%- if name_column -%}{%- if receives.name -%}`{{ receives.name }}`{%- endif %} | {% endif %}{% if receives.annotation -%}{%- with expression = receives.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ receives.description|newline_to_br }}
+{%- if name_column -%}{%- if receives.name -%}`{{ receives.name }}`{%- endif %} | {% endif %}{% if receives.annotation -%}{%- with expression = receives.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ receives.description|newline_to_br }}
 {% endfor %}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/returns.md.jinja

@@ -6,7 +6,7 @@
 {% if name_column -%}Name | {% endif -%}Type | Description
 {% if name_column -%}---- | {% endif -%}---- | -----------
 {% for returns in section.value %}
-{%- if name_column -%}{%- if returns.name -%}`{{ returns.name }}`{%- endif %} | {% endif %}{% if returns.annotation -%}{%- with expression = returns.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ returns.description|newline_to_br }}
+{%- if name_column -%}{%- if returns.name -%}`{{ returns.name }}`{%- endif %} | {% endif %}{% if returns.annotation -%}{%- with expression = returns.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ returns.description|newline_to_br }}
 {% endfor %}
 
 {%- elif config.docstring_section_style == "list" %}

src/griffe2md/templates/docstring/warns.md.jinja

@@ -5,7 +5,7 @@
 Type | Description
 ---- | -----------
 {% for warns in section.value %}
-{%- if warns.annotation -%}{%- with expression = warns.annotation -%}<code>{% filter replace("|", "&#124;") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif -%} | {{ warns.description|newline_to_br }}
+{%- if warns.annotation -%}{%- with expression = warns.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif -%} | {{ warns.description|newline_to_br }}
 {% endfor %}
 
 {%- elif config.docstring_section_style == "list" %}