markdown-environments 1.0.0__py3-none-any.whl

markdown_environments/__init__.py

@@ -0,0 +1,18 @@
+r"""
+The base Markdown syntax defined by this extension is::
+
+    \begin{...}
+    ...
+    \end{...}
+
+Note that there must be a blank line before each `\\begin{}` and after each `\\end{}`.
+"""
+
+from .captioned_figure import CaptionedFigureExtension
+from .cited_blockquote import CitedBlockquoteExtension
+from .div import DivExtension
+from .dropdown import DropdownExtension
+from .thms import ThmsExtension
+
+
+__version__ = "1.0.0"

markdown_environments/captioned_figure.py

@@ -0,0 +1,165 @@
+import re
+import xml.etree.ElementTree as etree
+
+from markdown.blockprocessors import BlockProcessor
+from markdown.extensions import Extension
+
+from . import util
+from .mixins import HtmlClassMixin
+
+
+class CaptionedFigureProcessor(BlockProcessor, HtmlClassMixin):
+
+    RE_FIGURE_START = r"^\\begin{captioned_figure}"
+    RE_FIGURE_END = r"^\\end{captioned_figure}"
+    RE_CAPTION_START = r"^\\begin{caption}"
+    RE_CAPTION_END = r"^\\end{caption}"
+
+    def __init__(self, *args, html_class: str, caption_html_class: str, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.init_html_class(html_class)
+        self.caption_html_class = caption_html_class
+
+    def test(self, parent, block):
+        return re.match(self.RE_FIGURE_START, block, re.MULTILINE)
+
+    def run(self, parent, blocks):
+        org_blocks = list(blocks)
+
+        # remove figure starting delim
+        blocks[0] = re.sub(self.RE_FIGURE_START, "", blocks[0], flags=re.MULTILINE)
+
+        # find and remove caption starting delim
+        caption_start_i = None
+        for i, block in enumerate(blocks):
+            if re.match(self.RE_CAPTION_START, block, re.MULTILINE):
+                # remove ending delim and note which block captions started on
+                # (as caption content itself is an unknown number of blocks)
+                caption_start_i = i
+                blocks[i] = re.sub(self.RE_CAPTION_START, "", block, flags=re.MULTILINE)
+                break
+
+        # if no starting delim for caption, restore and do nothing
+        if caption_start_i is None:
+            # `blocks = org_blocks` doesn't work since lists are passed by pointer in Python (value of reference)
+            # so changing the address of `blocks` only updates the local copy of it (the pointer)
+            # we need to change the values pointed to by `blocks` (its list elements)
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+
+        # find and remove caption ending delim, and extract element
+        delim_found = False
+        for i, block in enumerate(blocks[caption_start_i:], start=caption_start_i):
+            if re.search(self.RE_CAPTION_END, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.RE_CAPTION_END, "", block, flags=re.MULTILINE)
+                # build HTML for caption
+                elem_caption = etree.Element("figcaption")
+                if self.caption_html_class != "":
+                    elem_caption.set("class", self.caption_html_class)
+                self.parser.parseBlocks(elem_caption, blocks[caption_start_i:i + 1])
+                # remove used blocks
+                for _ in range(caption_start_i, i + 1):
+                    blocks.pop(caption_start_i)
+                break
+        # if no ending delim for caption, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+
+        # find and remove figure ending delim, and extract element
+        delim_found = False
+        for i, block in enumerate(blocks):
+            if re.search(self.RE_FIGURE_END, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.RE_FIGURE_END, "", block, flags=re.MULTILINE)
+                # build HTML for figure
+                elem_figure = etree.SubElement(parent, "figure")
+                if self.html_class != "":
+                    elem_figure.set("class", self.html_class)
+                self.parser.parseBlocks(elem_figure, blocks[:i + 1])
+                elem_figure.append(elem_caption) # make sure captions come after everything else
+                # remove used blocks
+                for _ in range(i + 1):
+                    blocks.pop(0)
+                break
+        # if no ending delim for figure, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+        return True
+
+
+class CaptionedFigureExtension(Extension):
+    r"""
+    Any chunk of content, such as an image, with a caption underneath.
+
+    Example:
+        .. code-block:: py
+
+            import markdown
+            from markdown_environments import CaptionedFigureExtension
+
+            input_text = ...
+            output_text = markdown.markdown(input_text, extensions=[
+                CaptionedFigureExtension(html_class="never", caption_html_class="gonna")
+            ])
+
+    Markdown usage:
+        .. code-block:: md
+
+            \begin{captioned_figure}
+            <figure content>
+
+            \begin{caption}
+            <caption>
+            \end{caption}
+
+            \end{captioned_figure}
+
+        becomes…
+
+        .. code-block:: html
+
+            <figure class="[html_class]">
+              [figure content]
+              <figcaption class="[caption_html_class]">
+                [caption]
+              </figcaption>
+            </figure>
+
+        Note that the `caption` block can be placed anywhere within the `captioned_figure` block, as long as, of course,
+        there are blank lines before and after the `caption` block.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize captioned figure extension, with configuration options passed as the following keyword arguments:
+
+            - **html_class** (*str*) -- HTML `class` attribute to add to figures (default: `""`).
+            - **caption_html_class** (*str*) -- HTML `class` attribute to add to captions (default: `""`).
+        """
+
+        self.config = {
+            "html_class": [
+                "",
+                "HTML `class` attribute to add to captioned figure (default: `\"\"`)."
+            ],
+            "caption_html_class": [
+                "",
+                "HTML `class` attribute to add to captioned figure's caption (default: `\"\"`)."
+            ]
+        }
+        util.init_extension_with_configs(self, **kwargs)
+
+    def extendMarkdown(self, md):
+        md.parser.blockprocessors.register(CaptionedFigureProcessor(md.parser, **self.getConfigs()), "captioned_figure", 105)
+
+
+def makeExtension(**kwargs):
+    return CaptionedFigureExtension(**kwargs)

markdown_environments/cited_blockquote.py

@@ -0,0 +1,162 @@
+import re
+import xml.etree.ElementTree as etree
+
+from markdown.blockprocessors import BlockProcessor
+from markdown.extensions import Extension
+
+from . import util
+from .mixins import HtmlClassMixin
+
+
+class CitedBlockquoteProcessor(BlockProcessor, HtmlClassMixin):
+
+    RE_BLOCKQUOTE_START = r"^\\begin{cited_blockquote}"
+    RE_BLOCKQUOTE_END = r"^\\end{cited_blockquote}"
+    RE_CITATION_START = r"^\\begin{citation}"
+    RE_CITATION_END = r"^\\end{citation}"
+
+    def __init__(self, *args, html_class: str, citation_html_class: str, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.init_html_class(html_class)
+        self.citation_html_class = citation_html_class
+
+    def test(self, parent, block):
+        return re.match(self.RE_BLOCKQUOTE_START, block, re.MULTILINE)
+
+    def run(self, parent, blocks):
+        org_blocks = list(blocks)
+
+        # remove blockquote starting delim
+        blocks[0] = re.sub(self.RE_BLOCKQUOTE_START, "", blocks[0], flags=re.MULTILINE)
+
+        # find and remove citation starting delim
+        delim_found = False
+        citation_start_i = None
+        for i, block in enumerate(blocks):
+            if re.match(self.RE_CITATION_START, block, re.MULTILINE):
+                delim_found = True
+                # remove ending delim and note which block citation started on
+                # (as citation content itself is an unknown number of blocks)
+                citation_start_i = i
+                blocks[i] = re.sub(self.RE_CITATION_START, "", block, flags=re.MULTILINE)
+                break
+        # if no starting delim for citation, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+
+        # find and remove citation ending delim (starting search from the citation start delim), and extract element
+        delim_found = False
+        for i, block in enumerate(blocks[citation_start_i:], start=citation_start_i):
+            if re.search(self.RE_CITATION_END, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.RE_CITATION_END, "", block, flags=re.MULTILINE)
+                # build HTML for citation
+                elem_citation = etree.Element("cite")
+                if self.citation_html_class != "":
+                    elem_citation.set("class", self.citation_html_class)
+                self.parser.parseBlocks(elem_citation, blocks[citation_start_i:i + 1])
+                # remove used blocks
+                for _ in range(citation_start_i, i + 1):
+                    blocks.pop(citation_start_i)
+                break
+        # if no ending delim for citation, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+
+        # find and remove blockquote ending delim, and extract element
+        delim_found = False
+        for i, block in enumerate(blocks):
+            if re.search(self.RE_BLOCKQUOTE_END, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.RE_BLOCKQUOTE_END, "", block, flags=re.MULTILINE)
+                # build HTML for blockquote
+                elem_blockquote = etree.SubElement(parent, "blockquote")
+                if self.html_class != "":
+                    elem_blockquote.set("class", self.html_class)
+                self.parser.parseBlocks(elem_blockquote, blocks[:i + 1])
+                parent.append(elem_citation) # make sure citation comes after everything else
+                # remove used blocks
+                for _ in range(i + 1):
+                    blocks.pop(0)
+                break
+        # if no ending delim for blockquote, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+        return True
+
+
+class CitedBlockquoteExtension(Extension):
+    r"""
+    A blockquote with a citation/quote attribution underneath.
+
+    Example:
+        .. code-block:: py
+
+            import markdown
+            from markdown_environments import CitedBlockquoteExtension
+
+            input_text = ...
+            output_text = markdown.markdown(input_text, extensions=[
+                CitedBlockquoteExtension(html_class="give", citation_html_class="you")
+            ])
+
+    Markdown usage:
+        .. code-block:: md
+
+            \begin{cited_blockquote}
+            <quote>
+
+            \begin{citation}
+            <citation>
+            \end{citation}
+
+            \end{cited_blockquote}
+
+        becomes…
+
+        .. code-block:: html
+
+            <blockquote class="[html_class]">
+              [quote]
+            </blockquote>
+            <cite class="[citation_html_class]">
+              [citation]
+            </cite>
+
+        Note that the `citation` block can be placed anywhere within the `cited_blockquote` block.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initialize cited blockquote extension, with configuration options passed as the following keyword arguments:
+
+            - **html_class** (*str*) -- HTML `class` attribute to add to blockquotes. Defaults to `""`.
+            - **citation_html_class** (*str*) -- HTML `class` attribute to add to captions. Defaults to `""`.
+        """
+
+        self.config = {
+            "html_class": [
+                "",
+                "HTML `class` attribute to add to cited blockquote. Defaults to `\"\"`."
+            ],
+            "citation_html_class": [
+                "",
+                "HTML `class` attribute to add to cited blockquote's citation. Defaults to `\"\"`."
+            ]
+        }
+        util.init_extension_with_configs(self, **kwargs)
+
+    def extendMarkdown(self, md):
+        md.parser.blockprocessors.register(CitedBlockquoteProcessor(md.parser, **self.getConfigs()), "cited_blockquote", 105)
+
+
+def makeExtension(**kwargs):
+    return CitedBlockquoteExtension(**kwargs)

markdown_environments/div.py

@@ -0,0 +1,130 @@
+import re
+import xml.etree.ElementTree as etree
+
+from markdown.blockprocessors import BlockProcessor
+from markdown.extensions import Extension
+
+from . import util
+from .mixins import HtmlClassMixin, ThmMixin
+
+
+class DivProcessor(BlockProcessor, HtmlClassMixin, ThmMixin):
+
+    def __init__(self, *args, types: dict, html_class: str, is_thm: bool, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.init_thm(types, is_thm)
+        self.init_html_class(html_class)
+
+    def test(self, parent, block):
+        return ThmMixin.test(self, parent, block)
+
+    def run(self, parent, blocks):
+        org_block_start = blocks[0]
+        # generate default thm heading if applicable
+        prepend = self.gen_thm_heading_md(blocks[0])
+        # remove starting delim (after generating thm heading from it, if applicable)
+        blocks[0] = re.sub(self.re_start, "", blocks[0], flags=re.MULTILINE)
+
+        # find and remove ending delim, and extract element
+        delim_found = False
+        for i, block in enumerate(blocks):
+            if re.search(self.re_end, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.re_end, "", block, flags=re.MULTILINE)
+                # build HTML
+                elem = etree.SubElement(parent, "div")
+                if self.html_class != "" or self.type_opts.get("html_class") != "":
+                    elem.set("class", f"{self.html_class} {self.type_opts.get('html_class')}")
+                self.parser.parseBlocks(elem, blocks[0:i + 1])
+                # remove used blocks
+                for _ in range(0, i + 1):
+                    blocks.pop(0)
+                break
+        # if no ending delim, restore and do nothing
+        if not delim_found:
+            blocks[0] = org_block_start
+            return False
+
+        # add thm heading if applicable
+        self.prepend_thm_heading_md(elem, prepend)
+        return True
+
+
+class DivExtension(Extension):
+    r"""
+    A general-purpose `<div>` that you can tack on HTML `class` es to.
+
+    Example:
+        .. code-block:: py
+
+            import markdown
+            from markdown_environments import DivExtension
+
+            input_text = ...
+            output_text = markdown.markdown(input_text, extensions=[
+                DivExtension(html_class="up", types={
+                    type1: {},
+                    type2: {"html_class": "never"}
+                })
+            ])
+
+    Markdown usage:
+        .. code-block:: md
+
+            \begin{<type>}
+            <content>
+            \end{<type>}
+
+        becomes…
+
+        .. code-block:: html
+
+            <div class="[html_class] [type's html_class]">
+              [content]
+            </div>
+    """
+
+    def __init__(self, **kwargs):
+        r"""
+        Initialize div extension, with configuration options passed as the following keyword arguments:
+
+            - **types** (*dict*) -- Types of div environments to define. Defaults to `{}`.
+            - **html_class** (*str*) -- HTML `class` attribute to add to divs. Defaults to `""`.
+
+        The key for each type defined in `types` is inserted directly into the regex patterns that search for
+        `\\begin{<type>}` and `\\end{<type>}`, so anything you specify will be interpreted as regex. In addition, each
+        type's value is itself a dictionary with the following possible options:
+
+            - **html_class** (*str*) -- HTML `class` attribute to add to divs of that type. Defaults to `""`.
+        """
+
+        self.config = {
+            "types": [
+                {},
+                "Types of div environments to define. Defaults to `{}`."
+            ],
+            "html_class": [
+                "",
+                "HTML `class` attribute to add to div. Defaults to `\"\"`."
+            ],
+            "is_thm": [
+                False,
+                (
+                    "Whether to use theorem logic (e.g. heading); you shouldn't have to set this value."
+                    "Defaults to `False`."
+                )
+            ]
+        }
+        util.init_extension_with_configs(self, **kwargs)
+
+        # set default options for individual types
+        for type, opts in self.getConfig("types").items():
+            opts.setdefault("html_class", "")
+
+    def extendMarkdown(self, md):
+        md.parser.blockprocessors.register(DivProcessor(md.parser, **self.getConfigs()), "div", 105)
+
+
+def makeExtension(**kwargs):
+    return DivExtension(**kwargs)

markdown_environments/dropdown.py

@@ -0,0 +1,196 @@
+import re
+import xml.etree.ElementTree as etree
+
+from markdown.blockprocessors import BlockProcessor
+from markdown.extensions import Extension
+
+from . import util
+from .mixins import HtmlClassMixin, ThmMixin
+
+
+class DropdownProcessor(BlockProcessor, HtmlClassMixin, ThmMixin):
+
+    RE_SUMMARY_START = r"^\\begin{summary}"
+    RE_SUMMARY_END = r"^\\end{summary}"
+
+    def __init__(self, *args, types: dict, html_class: str, summary_html_class: str, content_html_class: str,
+            is_thm: bool, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.init_thm(types, is_thm)
+        self.init_html_class(html_class)
+        self.summary_html_class = summary_html_class
+        self.content_html_class = content_html_class
+
+    def test(self, parent, block):
+        return ThmMixin.test(self, parent, block)
+
+    def run(self, parent, blocks):
+        org_blocks = list(blocks)
+        # remove summary starting delim that must immediately follow dropdown's starting delim
+        # if no starting delim for summary and not a thm dropdown which should provide a default, restore and do nothing
+        if not self.is_thm and not re.match(self.RE_SUMMARY_START, blocks[1], re.MULTILINE):
+            blocks.clear() # `blocks = org_blocks` doesn't work; must mutate `blocks` instead of reassigning it
+            blocks.extend(org_blocks)
+            return False
+        blocks[1] = re.sub(self.RE_SUMMARY_START, "", blocks[1], flags=re.MULTILINE)
+
+        # remove dropdown starting delim
+        # first generate theorem heading from it to use as default summary if applicable
+        thm_heading_md = self.gen_thm_heading_md(blocks[0])
+        blocks[0] = re.sub(self.re_start, "", blocks[0], flags=re.MULTILINE)
+
+        # find and remove summary ending delim, and extract element
+        # `elem_summary` initialized outside loop since the loop isn't guaranteed here to find & initialize it
+        elem_summary = etree.Element("summary")
+        if self.summary_html_class != "":
+            elem_summary.set("class", self.summary_html_class)
+        has_valid_summary = self.is_thm
+        for i, block in enumerate(blocks):
+            # if we haven't found summary ending delim but have found the overall dropdown ending delim,
+            # then don't keep going; maybe the summary was omitted as it was optional for theorems
+            if re.search(self.re_end, block, flags=re.MULTILINE):
+                break
+            if re.search(self.RE_SUMMARY_END, block, flags=re.MULTILINE):
+                has_valid_summary = True
+                # remove ending delim
+                blocks[i] = re.sub(self.RE_SUMMARY_END, "", block, flags=re.MULTILINE)
+                # build HTML for summary
+                self.parser.parseBlocks(elem_summary, blocks[:i + 1])
+                # remove used blocks
+                for _ in range(i + 1):
+                    blocks.pop(0)
+                break
+        # if no valid summary (e.g. no ending delim with no default), restore and do nothing
+        if not has_valid_summary:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+        # add thm heading to summary if applicable
+        self.prepend_thm_heading_md(elem_summary, thm_heading_md)
+
+        # find and remove dropdown ending delim, and extract element
+        delim_found = False
+        for i, block in enumerate(blocks):
+            if re.search(self.re_end, block, flags=re.MULTILINE):
+                delim_found = True
+                # remove ending delim
+                blocks[i] = re.sub(self.re_end, "", block, flags=re.MULTILINE)
+                # build HTML for dropdown
+                elem_details = etree.SubElement(parent, "details")
+                if self.html_class != "" or self.type_opts.get("html_class") != "":
+                    elem_details.set("class", f"{self.html_class} {self.type_opts.get('html_class')}")
+                elem_details.append(elem_summary)
+                elem_details_content = etree.SubElement(elem_details, "div")
+                if self.content_html_class != "":
+                    elem_details_content.set("class", self.content_html_class)
+                self.parser.parseBlocks(elem_details_content, blocks[0:i + 1])
+                # remove used blocks
+                for _ in range(0, i + 1):
+                    blocks.pop(0)
+                break
+        # if no ending delim for dropdown, restore and do nothing
+        if not delim_found:
+            blocks.clear()
+            blocks.extend(org_blocks)
+            return False
+        return True
+
+
+class DropdownExtension(Extension):
+    r"""
+    A dropdown that can be toggled open or closed, with only a preview portion (`<summary>`) shown when closed.
+
+    Example:
+        .. code-block:: py
+
+            import markdown
+            from markdown_environments import DropdownExtension
+
+            input_text = ...
+            output_text = markdown.markdown(input_text, extensions=[
+                DropdownExtension(
+                    html_class="gonna", summary_html_class="let", content_html_class="you",
+                    types={
+                        type1: {"html_class": "down"},
+                        type2: {}
+                    }
+                )
+            ])
+
+    Markdown usage:
+        .. code-block:: md
+
+            \begin{<type>}
+
+            \begin{summary}
+            <summary>
+            \end{summary}
+
+            <collapsible content>
+            \end{<type>}
+
+        becomes…
+
+        .. code-block:: html
+
+            <details class="[html_class] [type's html_class]">
+              <summary class="[summary_html_class]">
+                [summary]
+              </summary>
+
+              <div class="[content_html_class]">
+                [collapsible content]
+              </div>
+            </details>
+    """
+
+    def __init__(self, **kwargs):
+        r"""
+        Initialize dropdown extension, with configuration options passed as the following keyword arguments:
+
+            - **types** (*dict*) -- Types of dropdown environments to define. Defaults to `{}`.
+            - **html_class** (*str*) -- HTML `class` attribute to add to dropdowns. Defaults to `""`.
+            - **summary_html_class** (*str*) -- HTML `class` attribute to add to dropdown summaries. Defaults to `""`.
+            - **content_html_class** (*str*) -- HTML `class` attribute to add to dropdown contents. Defaults to `""`.
+
+        The key for each type defined in `types` is inserted directly into the regex patterns that search for
+        `\\begin{<type>}` and `\\end{<type>}`, so anything you specify will be interpreted as regex. In addition, each
+        type's value is itself a dictionary with the following possible options:
+
+            - **html_class** (*str*) -- HTML `class` attribute to add to dropdowns of that type. Defaults to `""`.
+        """
+
+        self.config = {
+            "types": [
+                {},
+                "Types of dropdown environments to define. Defaults to `{}`."
+            ],
+            "html_class": [
+                "",
+                "HTML `class` attribute to add to dropdown. Defaults to `\"\"`."
+            ],
+            "summary_html_class": [
+                "",
+                "HTML `class` attribute to add to dropdown summary. Defaults to `\"\"`."
+            ],
+            "content_html_class": [
+                "",
+                "HTML `class` attribute to add to dropdown content. Defaults to `\"\"`."
+            ],
+            "is_thm": [
+                False,
+                "Whether to use theorem logic (e.g. heading); used only by `ThmExtension`. Defaults to `False`."
+            ]
+        }
+        util.init_extension_with_configs(self, **kwargs)
+
+        # set default options for individual types
+        for type, opts in self.getConfig("types").items():
+            opts.setdefault("html_class", "")
+
+    def extendMarkdown(self, md):
+        md.parser.blockprocessors.register(DropdownProcessor(md.parser, **self.getConfigs()), "dropdown", 105)
+
+
+def makeExtension(**kwargs):
+    return DropdownExtension(**kwargs)