MDit 0.0.0.dev0__tar.gz

mdit-0.0.0.dev0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: MDit
+Version: 0.0.0.dev0
+Requires-Python: >=3.10
+Requires-Dist: IPython
+Requires-Dist: PyProtocol
+Requires-Dist: markdown-it-py
+Requires-Dist: mdit-py-plugins
+Requires-Dist: linkify-it-py
+Requires-Dist: readme-renderer
+Requires-Dist: cmarkgfm

mdit-0.0.0.dev0/README.md

@@ -0,0 +1 @@
+# MDit

mdit-0.0.0.dev0/pyproject.toml

@@ -0,0 +1,31 @@
+
+[build-system]
+requires = ["setuptools>=61.0", "versioningit"]
+build-backend = "setuptools.build_meta"
+
+
+# ----------------------------------------- setuptools -------------------------------------------
+[tool.setuptools]
+include-package-data = true
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+
+# ----------------------------------------- Project Metadata -------------------------------------
+#
+[project]
+version = "0.0.0.dev0"
+name = "MDit"
+requires-python = ">=3.10"
+dependencies = [
+    "IPython",
+    "PyProtocol",
+    "markdown-it-py",
+    "mdit-py-plugins",
+    "linkify-it-py",
+    "readme-renderer",
+    "cmarkgfm",
+]

mdit-0.0.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mdit-0.0.0.dev0/src/MDit.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: MDit
+Version: 0.0.0.dev0
+Requires-Python: >=3.10
+Requires-Dist: IPython
+Requires-Dist: PyProtocol
+Requires-Dist: markdown-it-py
+Requires-Dist: mdit-py-plugins
+Requires-Dist: linkify-it-py
+Requires-Dist: readme-renderer
+Requires-Dist: cmarkgfm

mdit-0.0.0.dev0/src/MDit.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/MDit.egg-info/PKG-INFO
+src/MDit.egg-info/SOURCES.txt
+src/MDit.egg-info/dependency_links.txt
+src/MDit.egg-info/not-zip-safe
+src/MDit.egg-info/requires.txt
+src/MDit.egg-info/top_level.txt
+src/mdit/__init__.py
+src/mdit/container.py
+src/mdit/display.py
+src/mdit/element.py
+src/mdit/parse.py
+src/mdit/render.py

mdit-0.0.0.dev0/src/MDit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mdit-0.0.0.dev0/src/MDit.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

mdit-0.0.0.dev0/src/MDit.egg-info/requires.txt

@@ -0,0 +1,7 @@
+IPython
+PyProtocol
+markdown-it-py
+mdit-py-plugins
+linkify-it-py
+readme-renderer
+cmarkgfm

mdit-0.0.0.dev0/src/MDit.egg-info/top_level.txt

@@ -0,0 +1 @@
+mdit

mdit-0.0.0.dev0/src/mdit/__init__.py

@@ -0,0 +1,6 @@
+"""Generate and process Markdown content.
+
+References
+----------
+- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+"""

mdit-0.0.0.dev0/src/mdit/container.py

@@ -0,0 +1,71 @@
+from typing import Type as _Type
+
+from pyprotocol import Stringable as _Stringable
+
+
+ContentType = _Stringable
+ContentInputType = (
+    dict[str | int, ContentType]
+    | list[ContentType]
+    | tuple[ContentType]
+    | None
+)
+
+
+class Container(_Stringable):
+
+    def __init__(self, *unlabeled_contents: ContentType, **labeled_contents: ContentType):
+        self._data = {}
+        self.add(*unlabeled_contents, **labeled_contents)
+        return
+
+    def add(self, *unlabeled_contents: ContentType, **labeled_contents: ContentType) -> list[int] | None:
+        if labeled_contents:
+            for key, value in labeled_contents.items():
+                if key in self._data:
+                    raise ValueError("Key already exists in content.")
+                self._data[key] = value
+        if unlabeled_contents:
+            first_available_int_key = max(key for key in self._data.keys() if isinstance(key, int)) + 1
+            for idx, elem in enumerate(unlabeled_contents):
+                self._data[first_available_int_key + idx] = elem
+            return list(range(first_available_int_key, first_available_int_key + len(unlabeled_contents)))
+        return
+
+    def get(self, key: str | int, default=None):
+        return self._data.get(key, default)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()
+
+    def __getitem__(self, item):
+        return self._data[item]
+
+    def __setitem__(self, key, value):
+        self._data[key] = value
+        return
+
+    def __contains__(self, item):
+        return item in self._data
+
+    def __bool__(self):
+        return bool(self._data)
+
+
+def create(
+    content: ContentInputType,
+    container_class: _Type[Container] = Container
+) -> Container:
+    if not content:
+        return container_class()
+    if isinstance(content, dict):
+        return container_class(**content)
+    if isinstance(content, (list, tuple)):
+        return container_class(*content)
+    return container_class(content)

mdit-0.0.0.dev0/src/mdit/display.py

@@ -0,0 +1,52 @@
+"""Display HTML and Markdown content in web browser or IPython notebook."""
+
+import webbrowser as _webbrowser
+import tempfile as _tempfile
+import time as _time
+from pathlib import Path as _Path
+
+from IPython import display as _display
+
+
+def browser(content: str) -> None:
+    """Display HTML content in a web browser.
+
+    This function writes the content to a temporary file and opens it in the system's default web browser.
+    It then waits for 10 seconds (ensuring the browser has enough time to load the content)
+    before deleting the temporary file.
+
+    Parameters
+    ----------
+    content : str
+        HTML content to display.
+    """
+    with _tempfile.NamedTemporaryFile('w', delete=False, suffix='.html') as temp_file:
+        temp_file.write(content)
+        temp_file.flush()
+        temp_filepath = temp_file.name
+    _webbrowser.open(f'file://{temp_filepath}')
+    _time.sleep(10)
+    _Path(temp_filepath).unlink()
+    return
+
+
+def ipython(content: str, as_md: bool = False) -> None:
+    """Display HTML or Markdown content in an IPython notebook.
+
+    This function uses the `IPython.display` module to render the content
+    in the current cell of an IPython notebook.
+
+    Parameters
+    ----------
+    content : str
+        HTML or Markdown content to display.
+    as_md : bool, default: False
+        If True, the function uses the `IPython.display.Markdown` renderer,
+        otherwise (by default) it uses the `IPython.display.HTML` renderer
+    """
+    if ipython:
+        renderer = _display.Markdown if as_md else _display.HTML
+        _display.display(renderer(content))
+        return
+
+    return

mdit-0.0.0.dev0/src/mdit/element.py

@@ -0,0 +1,558 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+if _TYPE_CHECKING:
+    from typing import Literal
+
+
+class Element:
+    def __init__(
+        self,
+        block: bool,
+        leaf: bool = True,
+        contents: _ElementContentInputType = None,
+        newlines_before: int | None = None,
+        newlines_after: int | None = None,
+    ):
+        super().__init__(contents=contents)
+        self._block = block
+        self._leaf = leaf
+        self.newlines_before = newlines_before
+        self.newlines_after = newlines_after
+        return
+
+    def __str__(self):
+        if not self._block:
+            if any(not isinstance(elem, str) for elem in self._content.values()):
+                raise ValueError("Inline elements must have string content.")
+        elif self._leaf:
+            if any(isinstance(elem, Element) and elem.is_block for elem in self._content.values()):
+                raise ValueError("Leaf block elements cannot contain block content.")
+        content = "".join(str(elem) for elem in self._content.values())
+        md = self._md.replace("${{content}}", content)
+        newlines_before, newlines_after = [
+            newlines_count if isinstance(newlines_count, int) else (1 if self._block else 0)
+            for newlines_count in (self.newlines_before, self.newlines_after)
+        ]
+        return f"{newlines_before * '\n'}{md}{newlines_after * '\n'}"
+
+    @property
+    def _md(self) -> str:
+        return "${{content}}"
+
+    @property
+    def is_block(self) -> bool:
+        return self._block
+
+    @property
+    def is_leaf(self) -> bool:
+        return self._leaf
+
+    def display(self, ipython: bool = True, as_md: bool = True) -> None:
+        """Display the element in an IPython notebook."""
+        super().display(ipython=ipython, as_md=as_md)
+        return
+
+
+class ThematicBreak(Element):
+    def __init__(self, char: Literal["-", "_", "*"] = "-"):
+        super().__init__(block=True)
+        self.char = char
+        return
+
+    @property
+    def char(self):
+        return self._char
+
+    @char.setter
+    def char(self, value: _Literal["-", "_", "*"]):
+        if value not in ("-", "_", "*"):
+            raise ValueError("Invalid thematic break character.")
+        self._char = value
+        return
+
+    @property
+    def _md(self) -> str:
+        return self.char * 3
+
+
+class ATXHeading(Element):
+    def __init__(self, level: _Literal[1, 2, 3, 4, 5, 6], contents: _ElementContentInputType = ""):
+        super().__init__(block=True, leaf=True, contents=contents)
+        self._level = level
+        return
+
+    @property
+    def level(self):
+        return self._level
+
+    @level.setter
+    def level(self, value: _Literal[1, 2, 3, 4, 5, 6]):
+        if value not in (1, 2, 3, 4, 5, 6):
+            raise ValueError("Invalid heading level.")
+        self._level = value
+        return
+
+    @property
+    def _md(self) -> str:
+        return f"{'#' * self.level} ${{content}}"
+
+
+class FieldListElement(Element):
+    def __init__(self, name: _ElementContentType, body: _ElementContentInputType = "", indent_size: int = 4):
+        super().__init__(block=True, leaf=False, contents=body)
+        self.name = name
+        self.indent_size = indent_size
+        return
+
+    @property
+    def _md(self) -> str:
+        body = "".join(str(elem) for elem in self._content.values())
+        first_line, *lines = body.strip().split("\n")
+        body = "\n".join([first_line] + [f"{' ' * self.indent_size}{line}" for line in lines])
+        return f":{self.name}: {body}".strip()
+
+
+class FieldList(Element):
+    def __init__(self, elements: list[FieldListElement], indent_size: int = 4):
+        super().__init__(block=True, leaf=False)
+        self.indent_size = indent_size
+        self.elements = elements
+        return
+
+    @property
+    def _md(self) -> str:
+        elements_md = []
+        for elem in self.elements:
+            indent_orig = elem.indent_size
+            elem.indent_size = self.indent_size
+            elements_md.append(elem._md)
+            elem.indent_size = indent_orig
+        return "\n".join(elements_md)
+
+
+class HTMLBlock(Element):
+
+    def __init__(self, contents: _ElementContentInputType = None):
+        super().__init__(block=True, leaf=True, contents=contents, newlines_after=2)
+        return
+
+    @property
+    def _md(self) -> str:
+        return "${{content}}"
+
+
+class CodeFence(Element):
+
+    def __init__(
+        self,
+        contents: _ElementContentInputType = None,
+        info: _Stringable = "",
+        fence: _Literal["`", "~", ":"] = "`",
+    ):
+        super().__init__(block=True, leaf=False, contents=contents)
+        self._info = info
+        self.fence = fence
+        return
+
+    @property
+    def info(self) -> _Stringable:
+        return self._info
+
+    @info.setter
+    def info(self, value: _Stringable):
+        if "\n" in str(value):
+            raise ValueError("Info string cannot contain newlines.")
+        self._info = value
+        return
+
+    @property
+    def fence(self):
+        return self._fence
+
+    @fence.setter
+    def fence(self, value: _Literal["`", "~", ":"]):
+        if value not in ("`", "~", ":"):
+            raise ValueError("Invalid code fence character.")
+        self._fence = value
+        return
+
+    @property
+    def _md(self) -> str:
+        return f"{self._start_line}\n${{content}}\n{self._end_line}"
+
+    @property
+    def fence_count(self):
+        return max(
+            [child.fence_count for child in self.content.values() if isinstance(child, CodeFence)],
+            default=3
+        )
+
+    @property
+    def _start_line(self) -> str:
+        return f"{self.fence * self.fence_count}{self.info}"
+
+    @property
+    def _end_line(self) -> str:
+        return self.fence * self.fence_count
+
+
+class Directive(CodeFence):
+    def __init__(
+        self,
+        name: _Stringable,
+        contents: _ElementContentInputType = None,
+        arg: _Stringable = "",
+        options: dict[_Stringable, _Stringable] | None = None,
+        fence: _Literal["`", "~", ":"] = "`",
+    ):
+        super().__init__(contents=contents, fence=fence)
+        self.name = name
+        self.arg = arg
+        self.options = options or {}
+        return
+
+    @property
+    def info(self) -> str:
+        return f"{{{self.name}}} {self.arg}"
+
+    @property
+    def _md(self) -> str:
+        options = []
+        for key, value in self.options.items():
+            val_str = str(value) if value is not None else ""
+            if "\n" in val_str:
+                val_content = "\n".join(f"{' ' * 4}{line}" for line in val_str.split("\n"))
+                val_str = f"|\n{val_content}"
+            options.append(f":{key}: {val_str}")
+        options = "\n".join(options)
+        options_section = f"{options}\n\n" if options else ""
+        return f"{self._start_line}\n{options_section}${{content}}\n{self._end_line}"
+
+
+def thematic_break(char: _Literal["-", "_", "*"] = "-") -> ThematicBreak:
+    """Create a [thematic break](https://github.github.com/gfm/#thematic-break).
+
+    Parameters
+    ----------
+    char : {'*', '_', '-'}, default: '-'
+        Thematic break character.
+    """
+    return ThematicBreak(char=char)
+
+
+def heading(level: _Literal[1, 2, 3, 4, 5, 6], content: _ElementContentInputType = "") -> ATXHeading:
+    """Create an ATX heading.
+
+    Parameters
+    ----------
+    level : {1, 2, 3, 4, 5, 6}
+        Heading level.
+    content : str
+        Heading content.
+    """
+    return ATXHeading(level=level, contents=content)
+
+
+def field_list_element(
+    name: _ElementContentType,
+    body: _ElementContentInputType = "",
+    indent_size: int = 4,
+) -> FieldListElement:
+    """Create a field list element.
+
+    Parameters
+    ----------
+    name : ElementContentType
+        Field name.
+    body : ElementContentInputType, optional
+        Field body.
+    indent_size : int, default: 4
+        Indent size.
+    """
+    return FieldListElement(name=name, body=body, indent_size=indent_size)
+
+
+def field_list(
+    elements: list[FieldListElement | tuple[_ElementContentType, _ElementContentInputType]],
+    indent_size: int = 4,
+) -> FieldList:
+    """Create a field list.
+
+    Parameters
+    ----------
+    elements : list[FieldListElement]
+        Field list elements.
+    indent_size : int, default: 4
+        Indent size.
+    """
+    elements = [
+        elem if isinstance(elem, FieldListElement) else field_list_element(name=elem[0], body=elem[1])
+        for elem in elements
+    ]
+    return FieldList(elements=elements, indent_size=indent_size)
+
+
+def html_block(content: _ElementContentInputType = None) -> HTMLBlock:
+    """Create an [HTML block](https://github.github.com/gfm/#html-block).
+
+    Parameters
+    ----------
+    content : ElementContentInputType, optional
+        HTML content.
+    """
+    return HTMLBlock(contents=content)
+
+def code_fence(
+    content: _ElementContentInputType = None,
+    info: _Stringable = "",
+    fence: _Literal["`", "~", ":"] = "`",
+) -> CodeFence:
+    """Create a [fenced code block](https://github.github.com/gfm/#fenced-code-block).
+
+    Parameters
+    ----------
+    content : ElementContentInputType, optional
+        Code block content.
+    info : Stringable, optional
+        Code block [info string](https://github.github.com/gfm/#info-string).
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    return CodeFence(contents=content, info=info, fence=fence)
+
+
+def directive(
+    name: _Stringable,
+    content: _ElementContentInputType = None,
+    arg: _Stringable = "",
+    options: dict[_Stringable, _Stringable] | None = None,
+    fence: _Literal["`", "~", ":"] = "`",
+) -> Directive:
+    """Create a directive.
+
+    Parameters
+    ----------
+    name : Stringable
+        Directive name.
+    content : ElementContentInputType, optional
+        Directive content.
+    arg : Stringable, optional
+        Directive argument.
+    options : dict[Stringable, Stringable], optional
+        Directive options.
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    return Directive(name=name, contents=content, arg=arg, options=options, fence=fence)
+
+
+def admonition(
+    title: _ElementContentType,
+    content: _ElementContentInputType,
+    class_: str | list[str] | None = None,
+    name: _Stringable | None = None,
+    fence: _Literal["`", "~", ":"] = "`",
+) -> Directive:
+    """Create a [MyST admonition](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).
+
+    Parameters
+    ----------
+    title : ElementContentType
+        Admonition title.
+    content : ElementContentInputType
+        Admonition content.
+    class_ : str | list[str], optional
+        CSS class names to add to the admonition. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    name : Stringable, optional
+        A reference target name for the admonition
+        (for [cross-referencing](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#syntax-referencing)).
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    options = process_directive_options({"class": class_, "name": name})
+    return Directive(name="admonition", contents=content, arg=title, options=options, fence=fence)
+
+
+def code_block(
+    language: str | None,
+    content: _ElementContentType,
+    caption: _ElementContentType | None = None,
+    class_: str | list[str] | None = None,
+    name: _Stringable | None = None,
+    lineno_start: int | None = None,
+    emphasize_lines: list[int] | None = None,
+    force: bool = False,
+    fence: _Literal["`", "~", ":"] = "`",
+):
+    """Create a MyST [code block directive](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#adding-a-caption).
+
+    Parameters
+    ----------
+    language : str, optional
+        Language of the code, e.g. 'python', 'json', 'bash', 'html'.
+    content : ElementContentType
+        Code to be included in the code block.
+    caption : ElementContentType, optional
+        Caption for the code block.
+    class_ : list[str], optional
+        CSS class names to add to the code block. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    name : Stringable, optional
+        A reference target name for the code block
+        (for [cross-referencing](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#syntax-referencing)).
+    lineno_start : int, optional
+        Starting line number for the code block.
+    emphasize_lines : list[int], optional
+        Line numbers to highlight in the code block.
+        Note that `lineno-start` must be set for this to work.
+    force : bool, default: False
+        Allow minor errors on highlighting to be ignored.
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    options = process_directive_options(
+        {k: v for k, v in locals() if k not in ("language", "content", "fence")}
+    )
+    return Directive(name="code-block", contents=content, arg=language, options=options, fence=fence)
+
+
+def tab_item(
+    title: _Stringable,
+    content: _ElementContentInputType,
+    selected: bool = False,
+    name: _Stringable | None = None,
+    sync: _Stringable | None = None,
+    class_container: str | list[str] | None = None,
+    class_label: str | list[str] | None = None,
+    class_content: str | list[str] | None = None,
+    fence: _Literal["`", "~", ":"] = "`",
+) -> Directive:
+    """Create a [Sphinx-Design tab item](https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html).
+
+    Parameters
+    ----------
+    title : Stringable
+        Tab title.
+    content : ElementContentInputType
+        Tab content.
+    selected : bool, default: False
+        Whether the tab item is selected by default.
+    name : Stringable, optional
+        A reference target name for the tab item
+        (for [cross-referencing](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#syntax-referencing)).
+    sync : Stringable, optional
+        A key that is used to sync the selected tab across multiple tab-sets.
+    class_container : str | list[str], optional
+        CSS class names to add to the container element. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    class_label : str | list[str], optional
+        CSS class names to add to the label element. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    class_content : str | list[str], optional
+        CSS class names to add to the content element. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    options = process_directive_options(
+        {k: v for k, v in locals() if k not in ("title", "content", "fence")}
+    )
+    return Directive(name="tab-item", contents=content, arg=title, options=options, fence=fence)
+
+
+def tab_set(
+    content: list[Directive],
+    class_: list[str] | None = None,
+    sync_group: _Stringable | None = None,
+    fence: _Literal["`", "~", ":"] = "`",
+) -> Directive:
+    """Create a [Sphinx-Design tab set](https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html).
+
+    Parameters
+    ----------
+    content : list[Directive]
+        Tab items.
+    class_ : list[str], optional
+        CSS class names to add to the tab set. These must conform to the
+        [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
+    sync_group : Stringable, optional
+        Group name for synchronized tab sets.
+    fence: {'`', '~', ':'}, default: '`'
+        Fence character.
+    """
+    options = process_directive_options(
+        {k: v for k, v in locals() if k not in ("content", "fence")}
+    )
+    return Directive(name="tab-set", contents=content, options=options, fence=fence)
+
+
+def card(
+    header_content: _ElementContentInputType = None,
+    body_content: _ElementContentInputType = None,
+    footer_content: _ElementContentInputType = None,
+    body_title: _Stringable = "",
+    width: _Literal["auto"] | int | None = None,
+    margin: _Literal["auto", 0, 1, 2, 3, 4, 5] | tuple[_Literal["auto", 0, 1, 2, 3, 4, 5], ...] | None = None,
+    text_align: _Literal["left", "center", "right", "justify"] | None = None,
+    img_background: _Stringable | None = None,
+    img_top: _Stringable | None = None,
+    img_bottom: _Stringable | None = None,
+    img_alt: _Stringable | None = None,
+    link: _Stringable | None = None,
+    link_type: _Literal["url", "ref", "doc", "any"] | None = None,
+    link_alt: _Stringable | None = None,
+    shadow: _Literal["sm", "md", "lg", "none"] | None = None,
+    class_card: list[str] | None = None,
+    class_header: list[str] | None = None,
+    class_body: list[str] | None = None,
+    class_footer: list[str] | None = None,
+    class_title: list[str] | None = None,
+    class_img_top: list[str] | None = None,
+    class_img_bottom: list[str] | None = None,
+    fence: _Literal["`", "~", ":"] = "`",
+) -> Directive:
+
+    def process_content(content, key_prefix: str):
+        if isinstance(content, (list, tuple)):
+            return {f"{key_prefix}_{idx}": elem for idx, elem in enumerate(content)}
+        if not isinstance(content, dict):
+            return {key_prefix: content}
+        return content
+
+    options = process_directive_options(
+        {
+            k: v for k, v in locals() if k not in (
+                "header_content", "body_content", "footer_content", "body_title", "fence"
+            )
+        }
+    )
+    content = {}
+    if header_content:
+        for header_id, header in process_content(header_content, "header"):
+            content[header_id] = header
+        content["header_body_separator"] = "^^^"
+    if body_content:
+        for body_id, body in process_content(body_content, "body"):
+            content[body_id] = body
+    if footer_content:
+        content["body_footer_separator"] = "+++"
+        for footer_id, footer in process_content(footer_content, "footer"):
+            content[footer_id] = footer
+    return Directive(name="card", contents=content, arg=body_title, options=options, fence=fence)
+
+
+def process_directive_options(options: dict) -> dict:
+    final_options = {}
+    for key, val in options.items():
+        if val is None or val is False:
+            continue
+        if isinstance(val, (list, tuple)):
+            val = " ".join([str(e) for e in val])
+        elif isinstance(val, bool):
+            val = ""
+        key_name = str(key).removesuffix("_").replace("_", "-")
+        final_options[key_name] = val
+    return final_options
+

mdit-0.0.0.dev0/src/mdit/parse.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+import re as _re
+
+import pyserials as _ps
+
+
+def frontmatter(file_content: str) -> dict:
+    match = _re.match(r'^---+\s*\n(.*?)(?=\n---+\s*(\n|$))', file_content, _re.DOTALL)
+    if not match:
+        return {}
+    frontmatter_text = match.group(1).strip()
+    frontmatter_dict = _ps.read.yaml_from_string(frontmatter_text)
+    return frontmatter_dict
+
+
+def title(file_content: str) -> str | None:
+    match = _re.search(r"^# (.*)", file_content, _re.MULTILINE)
+    return match.group(1) if match else ""
+
+
+def toctree(file_content: str) -> tuple[str, ...] | None:
+    matches = _re.findall(r"(:{3,}){toctree}\s((.|\s)*?)\s\1", file_content, _re.DOTALL)
+    if not matches:
+        return
+    toctree_str = matches[0][1]
+    toctree_entries = []
+    for line in toctree_str.splitlines():
+        entry = line.strip()
+        if entry and not entry.startswith(":"):
+            toctree_entries.append(entry)
+    return tuple(toctree_entries)

mdit-0.0.0.dev0/src/mdit/render.py

@@ -0,0 +1,396 @@
+from typing import Literal as _Literal, Callable as _Callable
+from functools import partial as _partial
+import cmarkgfm as _gfm_pypi
+from readme_renderer import markdown as _readme_renderer_md, clean as _readme_renderer_clean
+
+
+
+
+import markdown_it as _mdit
+import markdown_it.utils as _mdit_utils
+
+from mdit_py_plugins.amsmath import amsmath_plugin as _mdit_plugin_amsmath
+from mdit_py_plugins.anchors import anchors_plugin as _mdit_plugin_anchors
+from mdit_py_plugins.attrs import attrs_block_plugin as _mdit_plugin_attrs_block, attrs_plugin as _mdit_plugin_attrs
+from mdit_py_plugins.colon_fence import colon_fence_plugin as _mdit_plugin_colon_fence
+from mdit_py_plugins.deflist import deflist_plugin as _mdit_plugin_deflist
+from mdit_py_plugins.dollarmath import dollarmath_plugin as _mdit_plugin_dollarmath
+from mdit_py_plugins.field_list import fieldlist_plugin as _mdit_plugin_fieldlist
+from mdit_py_plugins.footnote import footnote_plugin as _mdit_plugin_footnote
+from mdit_py_plugins.front_matter import front_matter_plugin as _mdit_plugin_front_matter
+from mdit_py_plugins.myst_blocks import myst_block_plugin as _mdit_plugin_myst_block
+from mdit_py_plugins.myst_role import myst_role_plugin as _mdit_plugin_myst_role
+from mdit_py_plugins.substitution import substitution_plugin as _mdit_plugin_substitution
+from mdit_py_plugins.tasklists import tasklists_plugin as _mdit_plugin_tasklists
+from mdit_py_plugins.wordcount import wordcount_plugin as _mdit_plugin_wordcount
+
+
+# from myst_parser.config.main import MdParserConfig
+
+
+def to_html(
+    source: str,
+    components_core: set[
+        _Literal['block', 'inline', 'linkify', 'normalize', 'replacements', 'smartquotes', 'text_join']
+    ] = ('block', 'inline', 'linkify', 'normalize', 'replacements', 'smartquotes', 'text_join'),
+    components_block: set[
+        _Literal[
+            'blockquote',
+            'code',
+            'fence',
+            'heading',
+            'hr',
+            'html_block',
+            'lheading',
+            'list',
+            'paragraph',
+            'reference',
+            'table',
+        ]
+    ] = (
+        'blockquote',
+        'code',
+        'fence',
+        'heading',
+        'hr',
+        'html_block',
+        'lheading',
+        'list',
+        'paragraph',
+        'reference',
+        'table',
+    ),
+    components_inline: set[
+        _Literal[
+            'autolink',
+            'backticks',
+            'balance_pairs',
+            'emphasis',
+            'entity',
+            'escape',
+            'fragments_join',
+            'html_inline',
+            'image',
+            'link',
+            'linkify',
+            'newline',
+            'strikethrough',
+            'text'
+        ]
+    ] = (
+            'autolink',
+            'backticks',
+            'balance_pairs',
+            'emphasis',
+            'entity',
+            'escape',
+            'fragments_join',
+            'html_inline',
+            'image',
+            'link',
+            'linkify',
+            'newline',
+            'strikethrough',
+            'text'
+    ),
+    plugins: set[_Callable | tuple[_Callable, dict]] = (
+        _partial(_mdit_plugin_amsmath, renderer=None),
+        _partial(
+            _mdit_plugin_anchors,
+            min_level=1,
+            max_level=6,
+            slug_func=None,
+            permalink=True,
+            permalinkSymbol='¶',
+            permalinkBefore=False,
+            permalinkSpace=True,
+        ),
+        _partial(
+            _mdit_plugin_attrs,
+            after=('image', 'code_inline', 'link_close', 'span_close'),
+            spans=True,
+            span_after='link',
+        ),
+        _mdit_plugin_attrs_block,
+        _mdit_plugin_colon_fence,
+        _mdit_plugin_deflist,
+        _partial(
+            _mdit_plugin_dollarmath,
+            allow_labels=True,
+            allow_space=True,
+            allow_digits=True,
+            allow_blank_lines=True,
+            double_inline=False,
+        ),
+        _mdit_plugin_fieldlist,
+        _partial(_mdit_plugin_footnote, inline=True, move_to_end=True, always_match_refs=True),
+        _mdit_plugin_front_matter,
+        _mdit_plugin_myst_block,
+        _mdit_plugin_myst_role,
+        _partial(_mdit_plugin_substitution, start_delimiter='{', end_delimiter='}'),
+        _partial(_mdit_plugin_tasklists, enabled=False, label=False, label_after=False),
+        _partial(_mdit_plugin_wordcount, per_minute=200, store_text=False),
+    ),
+    env: dict | None = None,
+    html: bool = True,
+    linkify: bool = True,
+    linkify_fuzzy_links: bool = True,
+    typographer: bool = True,
+    quotes: str = '“”‘’',
+    xhtml_out: bool = True,
+    breaks: bool = True,
+    lang_prefix: str = 'language-',
+    highlight: _Callable[[str, str, str], str] = None,
+):
+    """Convert Markdown to HTML using the [`markdown-it-py`](https://markdown-it-py.readthedocs.io/) library.
+    
+    Parameters
+    ----------
+    source : str
+        Markdown source text to convert to HTML.
+    components_core : set of {'block', 'inline', 'linkify', 'normalize', 'replacements', 'smartquotes', 'text_join'}
+        Enabled core components
+        (cf. [`markdown-it-py` source code](https://github.com/executablebooks/markdown-it-py/tree/c10312e2e475a22edb92abede15d3dcabd0cac0c/markdown_it/rules_core)).
+    components_block : set of {'blockquote', 'code', 'fence', 'heading', 'hr', 'html_block', 'lheading', 'list', 'paragraph', 'reference', 'table'}
+        Enabled block components
+        (cf. [`markdown-it-py` source code](https://github.com/executablebooks/markdown-it-py/tree/c10312e2e475a22edb92abede15d3dcabd0cac0c/markdown_it/rules_block)).
+    components_inline : set of {'autolink', 'backticks', 'emphasis', 'entity', 'escape', 'html_inline', 'image', 'link', 'linkify', 'newline', 'strikethrough', 'text'}
+        Enabled inline components
+        (cf. [`markdown-it-py` source code](https://github.com/executablebooks/markdown-it-py/tree/c10312e2e475a22edb92abede15d3dcabd0cac0c/markdown_it/rules_inline)).
+    plugins : set of Callable[[MarkdownIt], None] or tuple[Callable[[MarkdownIt], None], dict], default: (front_matter_plugin,)
+        List of plugins to apply to the parser.
+        Each entry can either be a callable, or a tuple of a callable and a dictionary of keyword arguments.
+        The callable should take as its first argument the `MarkdownIt` parser instance,
+        followed by any additional arguments.
+        By default, all plugins from the [`mdit_py_plugins` library](https://mdit-py-plugins.readthedocs.io)
+        (cf. [source code](https://github.com/executablebooks/mdit-py-plugins/tree/d11bdaf0979e6fae01c35db5a4d1f6a4b4dd8843/mdit_py_plugins))
+        except for `admon_plugin`, `container_plugin`, and `texmath_plugin`
+        are enabled with their default configurations.
+    env : dict, optional
+        Environment variables to pass to the parser.
+        It is used to pass data between “distributed” rules and return additional metadata
+        like reference info, needed for the renderer.
+        It can also be used to inject data, e.g., when using the `substitution_plugin`.
+    html : bool, default: True
+        Allow raw HTML tags in the source text.
+    linkify : bool, default: True
+        Automatically convert URL-like text to links using the
+        [`linkify-it-py`](https://github.com/tsutsu3/linkify-it-py) library.
+    linkify_fuzzy_links : bool, default: True
+        Enable fuzzy link detection for `linkify`.
+        This allows URLs without a protocol schema (e.g., `repodynamics.com`) to be detected as links.
+    typographer : bool, default: True
+        Enable smartquotes and replacements.
+        This will automatically add the `smartquotes` and `replacements` core components as well.
+    quotes : str, default: '“”‘’'
+        Quote characters.
+    xhtml_out : bool, default: True
+        Use '/' to close single tags (e.g., `<br />`).
+    breaks : bool, default: True
+        Convert newlines in paragraphs into `<br>` tags.
+    lang_prefix : str, default: 'language-'
+        CSS language prefix for fenced blocks.
+    highlight: Callable[[str, str, str], str] or None, default: None
+        An optional highlighter function `f(content, language, attributes) -> str`
+        to apply syntax highlighting to code blocks.
+
+    References
+    ----------
+    - [`markdown-it` Parser options](https://markdown-it-py.readthedocs.io/en/latest/api/markdown_it.utils.html#markdown_it.utils.OptionsType)
+    """
+    options = _mdit_utils.OptionsType(
+        maxNesting=50,
+        html=html,
+        linkify=linkify,
+        typographer=typographer,
+        quotes=quotes,
+        xhtmlOut=xhtml_out,
+        breaks=breaks,
+        langPrefix=lang_prefix,
+        highlight=highlight,
+    )
+    inline_rules = []
+    inline_rules2 = []
+    # For some reason (?!), `markdown-it-py` has 'inline' and 'inline2' rules.
+    # Enabling 'emphasis' and 'strikethrough' adds them to both 'inline' and 'inline2',
+    # while enabling 'balance_pairs' and 'fragments_join' only adds them to 'inline2'.
+    # All other components are only added to 'inline'.
+    # See: https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser
+    # Code: https://github.com/executablebooks/markdown-it-py/blob/c10312e2e475a22edb92abede15d3dcabd0cac0c/markdown_it/parser_inline.py#L38-L51
+    # For simplicity we have merged 'inline' and 'inline2' inputs into the 'components_inline' parameter.
+    # Now we need to separate them again.
+    for rule in components_inline:
+        if rule in ("emphasis", "strikethrough"):
+            inline_rules.append(rule)
+            inline_rules2.append(rule)
+        elif rule in ("balance_pairs", "fragments_join"):
+            inline_rules2.append(rule)
+        else:
+            inline_rules.append(rule)
+    components = {
+        "core": {"rules": list(components_core)},
+        "block": {"rules": list(components_block)},
+        "inline": {"rules": inline_rules, "rules2": inline_rules2},
+    }
+    config = _mdit_utils.PresetType(options=options, components=components)
+    parser = _mdit.MarkdownIt(config=config)
+    if typographer:
+        parser.enable(["replacements", "smartquotes"])
+    if parser.linkify is not None:
+        parser.linkify.set({"fuzzy_link": linkify_fuzzy_links})
+    for plugin in plugins:
+        if isinstance(plugin, (list, tuple)):
+            plugin_func, plugin_config = plugin
+        else:
+            plugin_func = plugin
+            plugin_config = {}
+        parser.use(plugin_func, **plugin_config)
+    return parser.render(src=source, env=env)
+
+
+
+# def create_md_parser(
+#     config: MdParserConfig, renderer: Callable[[MarkdownIt], RendererProtocol]
+# ) -> MarkdownIt:
+#     """Return a Markdown parser with the required MyST configuration."""
+#
+#     md.options.update(
+#         {
+#             "typographer": typographer,
+#             "linkify": "linkify" in config.enable_extensions,
+#             "myst_config": config,
+#         }
+#     )
+#
+#     return md
+
+
+def gfm_to_html_pypi(
+    source: str,
+    extensions: tuple[str, ...] = ('autolink', 'strikethrough', 'table', 'tagfilter', 'tasklist'),
+    unsafe: bool = True,
+    smart: bool = False,
+    normalize: bool = False,
+    hard_breaks: bool = False,
+    no_breaks: bool = False,
+    source_pos: bool = False,
+    footnotes: bool = False,
+    validate_utf8: bool = False,
+    github_pre_lang: bool = True,
+    liberal_html_tag: bool = False,
+    strikethrough_double_tilde: bool = False,
+    table_prefer_style_attributes: bool = False,
+    highlight_code: bool = True,
+    sanitize: bool = True,
+):
+    """Convert CommonMark or GitHub Flavored Markdown to HTML
+    using the [CMarkGFM](https://github.com/theacodes/cmarkgfm) library.
+
+    CMarkGFM is the Markdown to HTML converter
+    used by the Python Packaging Authority (PyPA)'s
+    [`readme_renderer`](https://github.com/pypa/readme_renderer) library to render
+    [package READMEs on PYPI](https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme).
+    Using this function with the default arguments will exactly replicate the rendering
+    used by PyPI.
+
+    Parameters
+    ----------
+    source : str
+        GitHub Flavored Markdown source text to convert to HTML.
+    extensions : Sequence[str], default: ('autolink', 'strikethrough', 'table', 'tagfilter', 'tasklist')
+        List of extensions to enable on top of the CommonMark specifications.
+        The default value enables all GitHub Flavored Markdown extensions,
+        which are currently the only [available extensions in CMarkGFM](https://github.com/theacodes/cmarkgfm/blob/66b131cee950ad30cad9dfbf7f2360270ed105b8/src/cmarkgfm/cmark.py#L118C13-L118C74).
+    unsafe: bool, default: True
+        Allow rendering unsafe HTML (e.g., `<script>` elements)
+        and URLs (e.g., those starting with `javascript:`, `vbscript:`, `file:`, or `data:` (except for `image/png`, `image/gif`, `image/jpeg`, or `image/webp` media types)).
+        If set to False, raw HTML is replaced by a placeholder comment and
+        potentially dangerous URLs are replaced by an empty string.
+    smart: bool, default: False
+        Render smart punctuation.
+        This is roughly equivalent to the `smartquotes` and `replacements` typographic components
+        in [`markdown-it`](https://markdown-it-py.readthedocs.io/en/latest/using.html#typographic-components),
+        e.g., converting basic quote marks to their opening and closing variants, and `--` and `---`
+        to en-dash `–` and em-dash `—`, respectively.
+    normalize: bool, default: False
+        Consolidate adjacent text nodes.
+    hard_breaks: bool, default: False
+        Render line breaks within paragraphs as `<br>` tags.
+    no_breaks: bool, default: False
+        Render soft line breaks as spaces.
+    source_pos: bool, default: False
+        Add attribute `data-sourcepos` to HTML tags
+        indicating the corresponding line/column ranges in the input.
+    footnotes: bool, default: False
+        Parse footnotes.
+    validate_utf8: bool, default: False
+        Validate UTF-8 in the input before parsing,
+        replacing illegal sequences with the replacement character `U+FFFD`.
+    github_pre_lang: bool, default: True
+        Use GitHub style for indicating the language of code blocks.
+        If True (default), the code block's language defined in its info string will be used
+        as the value of the `lang` attribute of the `<pre>` element
+        (e.g., `<pre lang="python"><code>...</code></pre>`),
+        otherwise it will be used as the value of the `class` attribute of the `<code>` element
+        according to [highlight.js](https://highlightjs.org/) style
+        (e.g., `<pre><code class="language-python">...</code></pre>`).
+    liberal_html_tag: bool, default: False
+        Be liberal in interpreting inline HTML tags.
+    strikethrough_double_tilde: bool, default: False
+        Only parse strikethroughs if surrounded by exactly 2 tildes.
+        Gives some compatibility with redcarpet.
+    table_prefer_style_attributes: bool, default: False
+        Use style attributes to align table cells instead of align attributes.
+    highlight_code : bool, default: True
+        Apply syntax highlighting to code blocks using the [`Pygments`](https://pygments.org/) library.
+        This exactly replicates the rendering used in PyPI.
+        However, notice that `readme_renderer` uses a naive RegEx to detect `<pre>` HTML elements.
+        Thus, this may not work on custom-written `<pre>` elements
+        (i.e., those not generated from Markdown by CMarkGFM in the previous step).
+    sanitize : bool, default: True
+        Sanitize the HTML output using the [`nh3`](https://nh3.readthedocs.io/en/latest/)
+        library to remove potentially dangerous content.
+        PyPI uses this to prevent XSS attacks by allowing only a
+        [subset of HTML tags](https://github.com/pypa/readme_renderer/blob/1d0497c37a6033d791c74e800590dcd0d34f6e08/readme_renderer/clean.py#L20-L31)
+        and [attributes](https://github.com/pypa/readme_renderer/blob/1d0497c37a6033d791c74e800590dcd0d34f6e08/readme_renderer/clean.py#L33-L65).
+
+    Notes
+    -----
+    - [`twine check`](https://twine.readthedocs.io/en/stable/#twine-check) only works for
+      reStructuredText (reST) READMEs; it always passes for Markdown content
+      (cf. [`twine.commands.check._RENDERERS`](https://github.com/pypa/twine/blob/4f7cd66fa1ceba7f8de5230d3d4ebea0787f17e5/twine/commands/check.py#L32-L37))
+      and thus cannot be used to validate Markdown.
+
+    References
+    ----------
+    - [`cmarkgfm.cmark` module](https://github.com/theacodes/cmarkgfm/blob/66b131cee950ad30cad9dfbf7f2360270ed105b8/src/cmarkgfm/cmark.py)
+    - [`readme_renderer.markdown` module](https://github.com/pypa/readme_renderer/blob/1d0497c37a6033d791c74e800590dcd0d34f6e08/readme_renderer/markdown.py)
+    """
+    options = 0
+    for arg, cmark_arg in (
+        (unsafe, _gfm_pypi.Options.CMARK_OPT_UNSAFE),
+        (smart, _gfm_pypi.Options.CMARK_OPT_SMART),
+        (normalize, _gfm_pypi.Options.CMARK_OPT_NORMALIZE),
+        (hard_breaks, _gfm_pypi.Options.CMARK_OPT_HARDBREAKS),
+        (no_breaks, _gfm_pypi.Options.CMARK_OPT_NOBREAKS),
+        (source_pos, _gfm_pypi.Options.CMARK_OPT_SOURCEPOS),
+        (footnotes, _gfm_pypi.Options.CMARK_OPT_FOOTNOTES),
+        (validate_utf8, _gfm_pypi.Options.CMARK_OPT_VALIDATE_UTF8),
+        (github_pre_lang, _gfm_pypi.Options.CMARK_OPT_GITHUB_PRE_LANG),
+        (liberal_html_tag, _gfm_pypi.Options.CMARK_OPT_LIBERAL_HTML_TAG),
+        (strikethrough_double_tilde, _gfm_pypi.Options.CMARK_OPT_STRIKETHROUGH_DOUBLE_TILDE),
+        (table_prefer_style_attributes, _gfm_pypi.Options.CMARK_OPT_TABLE_PREFER_STYLE_ATTRIBUTES),
+    ):
+        if arg:
+            options |= cmark_arg
+
+    html_syntax: str = _gfm_pypi.markdown_to_html_with_extensions(
+        text=source,
+        options=options,
+        extensions=extensions,
+    )
+    if highlight_code:
+        html_syntax = _readme_renderer_md._highlight(html_syntax)
+    if sanitize:
+        html_syntax = _readme_renderer_clean.clean(html_syntax)
+    return html_syntax