mdformat-hugo 0.1.0__py3-none-any.whl

mdformat_hugo/__init__.py

@@ -0,0 +1,16 @@
+"""Mdformat plugin for Hugo-flavored Markdown."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+__version__ = version("mdformat-hugo")
+
+from ._plugin import CHANGES_AST, RENDERERS, update_mdit
+
+__all__ = [
+    "CHANGES_AST",
+    "RENDERERS",
+    "__version__",
+    "update_mdit",
+]

mdformat_hugo/_mdit_plugins/__init__.py

@@ -0,0 +1,3 @@
+"""Hugo markdown-it-py plugins."""
+
+from __future__ import annotations

mdformat_hugo/_mdit_plugins/shortcodes.py

@@ -0,0 +1,52 @@
+"""Hugo shortcode preservation parser plugin."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from markdown_it import MarkdownIt
+    from markdown_it.rules_inline import StateInline
+
+
+def shortcode_plugin(md: MarkdownIt) -> None:
+    """Plugin to parse and format Hugo shortcodes uniformly."""
+    md.inline.ruler.before("text", "hugo_shortcode", _shortcode_rule_wrapper)
+
+
+def _shortcode_rule_wrapper(state: StateInline, silent: bool) -> bool:  # noqa: FBT001 - wrapper required by markdown-it-py API signature
+    """Wrap shortcode rule to convert markdown-it-py boolean to named parameter."""
+    return _shortcode_rule(state, should_skip_token_creation=silent)
+
+
+def _shortcode_rule(state: StateInline, *, should_skip_token_creation: bool) -> bool:
+    """Parse Hugo shortcodes: {{< shortcode >}} and {{% shortcode %}}."""
+    pos = state.pos
+    if pos + 3 >= state.posMax or state.src[pos : pos + 3] not in {"{{<", "{{%"}:
+        return False
+
+    is_percent = state.src[pos : pos + 3] == "{{%"
+    close_marker = "%}}" if is_percent else ">}}"
+    content_start = pos + 3
+
+    pos = content_start
+    while pos < state.posMax:
+        if state.src[pos : pos + 3] == close_marker:
+            if not should_skip_token_creation:  # pragma: no branch
+                _create_shortcode_token(state, content_start, pos, is_percent=is_percent)
+            state.pos = pos + 3
+            return True
+        pos += 1
+    return False
+
+
+def _create_shortcode_token(state: StateInline, content_start: int, pos: int, *, is_percent: bool) -> None:
+    """Create a Hugo shortcode token."""
+    token = state.push("hugo_shortcode", "", 0)
+    token.content = state.src[content_start:pos].strip()
+    token.markup = "{{%" if is_percent else "{{<"
+
+
+__all__ = [
+    "shortcode_plugin",
+]

mdformat_hugo/_plugin.py

@@ -0,0 +1,34 @@
+"""Mdformat plugin interface for Hugo markdown."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from markdown_it import MarkdownIt
+    from mdformat.renderer.typing import Render
+
+from ._mdit_plugins.shortcodes import shortcode_plugin
+from ._renderer import render_fence, render_heading, render_hugo_shortcode, render_image
+
+CHANGES_AST: Final = True
+RENDERERS: Final[Mapping[str, Render]] = {
+    "hugo_shortcode": render_hugo_shortcode,
+    "heading": render_heading,
+    "image": render_image,
+    "fence": render_fence,
+}
+
+
+def update_mdit(mdit: MarkdownIt) -> None:
+    """Add Hugo-specific markdown-it-py plugins."""
+    mdit.use(shortcode_plugin)
+
+
+__all__ = [
+    "CHANGES_AST",
+    "RENDERERS",
+    "update_mdit",
+]

mdformat_hugo/_renderer.py

@@ -0,0 +1,104 @@
+"""Renderers for Hugo markdown elements."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from mdformat.renderer import RenderContext, RenderTreeNode
+
+FENCE_ATTRS_PATTERN: Final = re.compile(r"^(\S+)\s+\{([^}]+)\}$")
+INLINE_ATTRS_PATTERN: Final = re.compile(r"^(.*?)\s*\{([^}]+)\}\s*$")
+ATTR_PATTERN: Final = re.compile(r'\.([^\s{}=]+)|#([^\s{}=]+)|([^\s{}=]+)=(?:"([^"]*)"|([^\s{}]+))')
+
+
+def render_hugo_shortcode(node: RenderTreeNode, _context: RenderContext) -> str:
+    """Render Hugo shortcode with normalized formatting."""
+    content = " ".join(node.content.split())
+    is_percent = node.markup == "{{%"
+    open_delim, close_delim = ("{{%", "%}}") if is_percent else ("{{<", ">}}")
+    return f"{open_delim} {content} {close_delim}"
+
+
+def render_image(node: RenderTreeNode, _context: RenderContext) -> str:
+    """Render image with optional title attribute."""
+    src, alt, title = node.attrs.get("src", ""), node.content, node.attrs.get("title", "")
+    return f'![{alt}]({src} "{title}")' if title else f"![{alt}]({src})"
+
+
+def render_heading(node: RenderTreeNode, context: RenderContext) -> str:
+    """Render heading with optional attributes."""
+    markup = "#" * int(node.tag[1])
+    children_text = node.children[0].render(context) if node.children else ""
+
+    if match := INLINE_ATTRS_PATTERN.match(children_text):
+        text_part = match.group(1).strip()
+        attrs = _parse_attrs_from_string(match.group(2))
+        attrs_str = f" {_format_attrs(attrs)}"
+        return f"{markup} {text_part}{attrs_str}"
+
+    return f"{markup} {children_text}"
+
+
+def render_fence(node: RenderTreeNode, _context: RenderContext) -> str:
+    """Render code fence with optional attributes from info string."""
+    code_block = node.content
+    fence_char = "`"
+    fence_len = max(3, _longest_consecutive_sequence(code_block, fence_char) + 1)
+    fence = fence_char * fence_len
+
+    info_str = node.info or ""
+
+    if match := FENCE_ATTRS_PATTERN.match(info_str):
+        lang = match.group(1)
+        attrs = _parse_attrs_from_string(match.group(2))
+        info_str = f"{lang} {_format_attrs(attrs)}"
+
+    return f"{fence}{info_str}\n{code_block}{fence}"
+
+
+def _format_attrs(attrs: dict[str, str]) -> str:
+    """Format attributes dictionary with consistent ordering and sorted elements."""
+    parts = (
+        ([f"#{attrs['id']}"] if "id" in attrs else [])
+        + [f".{c}" for c in sorted(attrs.get("class", "").split()) if c]
+        + [
+            f'{k}="{v}"' if " " in v or "=" in v else f"{k}={v}"
+            for k, v in sorted(attrs.items())
+            if k not in {"id", "class"}
+        ]
+    )
+    return f"{{{' '.join(parts)}}}"
+
+
+def _parse_attrs_from_string(attr_str: str) -> dict[str, str]:
+    """Parse attribute string into dictionary, preserving quoted values."""
+    attrs: dict[str, str] = {}
+    for match in ATTR_PATTERN.finditer(attr_str):
+        if class_name := match.group(1):
+            attrs["class"] = f"{attrs.get('class', '')} {class_name}".strip()
+        elif id_value := match.group(2):
+            attrs["id"] = id_value
+        else:
+            key = match.group(3)
+            value = match.group(4) if match.group(4) is not None else match.group(5)
+            attrs[key] = value
+    return attrs
+
+
+def _longest_consecutive_sequence(text: str, char: str) -> int:
+    """Find longest consecutive sequence of char in text."""
+    longest = current = 0
+    for c in text:
+        current = current + 1 if c == char else 0
+        longest = max(longest, current)
+    return longest
+
+
+__all__ = [
+    "render_fence",
+    "render_heading",
+    "render_hugo_shortcode",
+    "render_image",
+]

mdformat_hugo-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: mdformat-hugo
+Version: 0.1.0
+Summary: Mdformat plugin for Hugo-flavored Markdown
+Project-URL: Documentation, https://mdformat-hugo.readthedocs.io
+Project-URL: Homepage, https://github.com/gaborbernat/mdformat-hugo
+Project-URL: Source, https://github.com/gaborbernat/mdformat-hugo
+Project-URL: Tracker, https://github.com/gaborbernat/mdformat-hugo/issues
+Maintainer-email: Bernát Gábor <gaborjbernat@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Bernát Gábor
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: formatter,hugo,markdown,mdformat
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: markdown-it-py>=3
+Requires-Dist: mdformat-config>=0.1.3
+Requires-Dist: mdformat-deflist>=0.1.2
+Requires-Dist: mdformat-footnote>=0.1.1
+Requires-Dist: mdformat-front-matters>=2
+Requires-Dist: mdformat-gfm-alerts>=1
+Requires-Dist: mdformat-gfm>=1
+Requires-Dist: mdformat-pyproject>=0.0.1
+Requires-Dist: mdformat-ruff>=0.1.3
+Requires-Dist: mdformat-shfmt>=0.1
+Requires-Dist: mdformat-web>=0.1
+Requires-Dist: mdformat>=0.7.17
+Requires-Dist: mdit-py-plugins>=0.4
+Description-Content-Type: text/markdown
+
+# mdformat-hugo
+
+[![PyPI](https://img.shields.io/pypi/v/mdformat-hugo?style=flat-square)](https://pypi.org/project/mdformat-hugo/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/mdformat-hugo.svg)](https://pypi.org/project/mdformat-hugo/)
+[![check](https://github.com/gaborbernat/mdformat-hugo/actions/workflows/check.yaml/badge.svg)](https://github.com/gaborbernat/mdformat-hugo/actions/workflows/check.yaml)
+
+Mdformat plugin for Hugo-flavored Markdown. Formats Hugo content files while preserving shortcodes and markdown
+attributes.
+
+## Features
+
+This plugin adds support for Hugo-specific markdown syntax:
+
+### Shortcode Formatting
+
+Hugo shortcodes are formatted with normalized whitespace.
+
+**Input:**
+
+```markdown
+{{<  ref   "documentation.md"  >}}
+{{%   note   %}}
+```
+
+**Output:**
+
+```markdown
+{{< ref "documentation.md" >}}
+{{% note %}}
+```
+
+Both `{{< >}}` (no markdown processing) and `{{% %}}` (markdown processed) shortcode styles are supported.
+
+### Markdown Attributes
+
+Hugo extends standard Markdown with [markdown attributes](https://gohugo.io/content-management/markdown-attributes/) --
+a syntax for attaching HTML attributes (IDs, classes, and key-value pairs) to rendered elements. Attributes are written
+in curly braces after the element they modify, e.g., `{#my-id .my-class key=value}`.
+
+This plugin normalizes attribute order and formatting:
+
+1. **IDs** (`#id`) come first
+1. **Classes** (`.class`) follow, sorted alphabetically
+1. **Key-value pairs** (`key=value`) come last, sorted alphabetically by key
+1. Values containing spaces or `=` are quoted: `key="hello world"`; otherwise unquoted: `key=value`
+
+**Headings:**
+
+```markdown
+## Introduction {.zebra .apple #intro}
+```
+
+Formats to:
+
+```markdown
+## Introduction {#intro .apple .zebra}
+```
+
+**Images:**
+
+```markdown
+![Logo](logo.png){width=300 .img-fluid height=200}
+```
+
+Formats to:
+
+```markdown
+![Logo](logo.png){.img-fluid height=200 width=300}
+```
+
+**Code blocks:**
+
+````
+```python {linenos=table .highlight #code}
+def hello():
+    print("world")
+```
+````
+
+Formats to:
+
+````
+```python {#code .highlight linenos=table}
+def hello():
+    print("world")
+```
+````
+
+### Additional Features
+
+This plugin bundles support for Hugo markdown features and code block formatting via dependencies:
+
+**Markdown syntax:**
+
+- [mdformat-gfm](https://github.com/hukkin/mdformat-gfm) - GFM tables, strikethrough, task lists, autolinks
+- [mdformat-front-matters](https://github.com/kyleking/mdformat-front-matters) - TOML/YAML/JSON frontmatter
+- [mdformat-gfm-alerts](https://github.com/KyleKing/mdformat-gfm-alerts) - Blockquote alerts (`[!NOTE]`, `[!WARNING]`)
+- [mdformat-footnote](https://github.com/executablebooks/mdformat-footnote) - Pandoc-style footnotes
+- [mdformat-deflist](https://github.com/executablebooks/mdformat-deflist) - Definition lists
+
+**Code block formatting:**
+
+- [mdformat-ruff](https://github.com/Freed-Wu/mdformat-ruff) - Format Python code blocks with ruff
+- [mdformat-shfmt](https://github.com/hukkin/mdformat-shfmt) - Format shell code blocks with shfmt
+- [mdformat-config](https://github.com/hukkin/mdformat-config) - Format JSON, YAML, TOML code blocks
+- [mdformat-web](https://github.com/hukkin/mdformat-web) - Format HTML, CSS, JavaScript code blocks
+- [mdformat-pyproject](https://github.com/csala/mdformat-pyproject) - Format pyproject.toml in code blocks
+
+## Usage
+
+```bash
+mdformat content/
+```

mdformat_hugo-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mdformat_hugo/__init__.py,sha256=3O9_sZqQ0vktjvdh5N65w3IlH7HdkzZgagoye0K9S2g,313
+mdformat_hugo/_plugin.py,sha256=WmcepcQiboxEsfTyWg7O5YlOpRzBUL4_2LvrFjAXSO4,821
+mdformat_hugo/_renderer.py,sha256=rkKnsuQXxhxFyd1g4_aEpZXOuULOIDZXRHyw_eRvhAw,3707
+mdformat_hugo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mdformat_hugo/_mdit_plugins/__init__.py,sha256=WxPImNCoI9EnVQll8jb4hox-JcscBfJcvHYy0RcAQIQ,71
+mdformat_hugo/_mdit_plugins/shortcodes.py,sha256=EirbXJdnJiaIMXBzQSdI4jqgQzcEkAHYwRBujdnRzVc,1830
+mdformat_hugo-0.1.0.dist-info/METADATA,sha256=9MD0qAGi5QKC_JRqOyAMpf_1ac-3Iy7tCfBTk1xBVic,6332
+mdformat_hugo-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mdformat_hugo-0.1.0.dist-info/entry_points.txt,sha256=VfcV4gU5q6xqI4b6stW4JKllUh8Cp9imJF-tfq-iCFo,49
+mdformat_hugo-0.1.0.dist-info/licenses/LICENSE,sha256=vOxHGaCaxBpCypg8AG7-s7tzNPEx-MqOSxGt6fWRjKQ,1071
+mdformat_hugo-0.1.0.dist-info/RECORD,,

mdformat_hugo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mdformat_hugo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mdformat.parser_extension]
+hugo = mdformat_hugo

mdformat_hugo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernát Gábor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.