markdown-environments 1.0.0__tar.gz

markdown_environments-1.0.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "monthly"

markdown_environments-1.0.0/.github/workflows/publish.yaml

@@ -0,0 +1,22 @@
+name: Build & Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write # needed for PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Hatch
+        run: pip install hatch
+      - name: Build package
+        run: hatch build
+      - name: Test package
+        run: hatch test
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # v1.12.3

markdown_environments-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# build
+dist/
+
+# docs
+docs/_build/
+
+# package manager
+venv/
+
+# python
+__pycache__/
+
+# testing
+.pytest_cache/
+.coverage
+
+# vim
+*.swp

markdown_environments-1.0.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# requirements needed to build documentation
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

markdown_environments-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+I don't expect this project to be huge, so feel free to drop an issue or pull request on [GitHub](https://github.com/AnonymousRand/python-markdown-environments) to report bugs or suggest features. Running tests and updating documentation before submitting a pull request is appreciated ^^
+
+## Setting Up Development Environment
+
+Install necessary packages in a virtual environment:
+```shell
+$ mkdir venv
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ pip install -r requirements.txt
+```
+
+## Running Tests
+
+Run `hatch test` in the project's root directory. Tests are located in `tests/`; carefully modify tests if adding new features.
+
+## Generating Documentation
+
+Module, class, and function documentation are generated automatically from docstrings by `sphinx.ext.autodoc`. To update the documentation, simply update the docstrings and Read the Docs will automatically run Sphinx to generate the documentation when your changes are merged. Alternatively, to generate documentation manually for testing, run `make html` in the `docs/` directory and then open `docs/_build/html/index.html` in a browser.
+
+Docstrings use Google style, although a sprinkle of reStructuredText/Sphinx is used for things like controlling syntax highlighting on code blocks.

markdown_environments-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AnonymousRand
+
+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.

markdown_environments-1.0.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: markdown-environments
+Version: 1.0.0
+Summary: Highly customizable extensions for Python-Markdown in the style of LaTeX environments/theorems
+Project-URL: Homepage, https://github.com/AnonymousRand/python-markdown-environments
+Project-URL: Documentation, https://github.com/AnonymousRand/python-markdown-environments#readme
+Project-URL: Issues, https://github.com/AnonymousRand/python-markdown-environments/issues
+Author: AnonymousRand
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: ~=3.10
+Requires-Dist: beautifulsoup4~=4.12.3
+Requires-Dist: lxml~=5.3.0
+Requires-Dist: markdown~=3.7
+Description-Content-Type: text/markdown
+
+# Markdown-Environments
+
+Replicating amsthm features and syntax in Markdown so you can publish mathematical papers in HTML—because what mathematician *hasn't* tried to publish to the very reputable journal called *Their Janky Flask Personal Site That No One Will Ever See*?
+
+This Python-Markdown extension uses LaTeX-like syntax
+```
+\begin{...}
+...
+\end{...}
+```
+to create enviroments such as captioned figures, general-purpose `<div>`s, dropdowns, and user-defined LaTeX-style theorems that can be styled with attached HTML `class`es.
+
+## Installation
+
+```
+pip install markdown-environments
+```
+
+## Available Environments
+
+- `\begin{captioned_figure}`: figures with captions
+- `\begin{cited_blockquote}`: blockquotes with quote attribution
+- User-defined environments wrapped in general-purpose `<div>`s to style to your heart's content
+- User-defined environments formatted as `<details>` and `<summary>` dropdowns
+- User-defined LaTeX theorem environments with customizable:
+    - Theorem counters
+    - Heading punctuation
+    - Linkable `id`s by theorem name
+
+## Further Reading
+
+Full documentation and detailed usage examples can be found [here](https://python-markdown-environments.readthedocs.io).
+
+<!-- example usage -->
+
+# Example Usage
+
+## Backend:
+
+```py
+import markdown
+from markdown_environments import ThmsExtension
+
+input_text = ...
+output_text = markdown.markdown(input_text, extensions=[
+    ThmsExtension(
+        div_config={
+            "types": {
+                "thm": {
+                    "thm_type": "Theorem",
+                    "html_class": "md-thm",
+                    "thm_counter_incr": "0,0,1"
+                },
+                r"thm\\\*": {
+                    "thm_type": "Theorem",
+                    "html_class": "md-thm"
+                }
+            },
+            "html_class": "md-div"
+        },
+        dropdown_config={
+            "types": {
+                "exer": {
+                    "thm_type": "Exercise",
+                    "html_class": "md-exer",
+                    "thm_counter_incr": "0,0,1",
+                    "thm_punct": ":",
+                    "use_punct_if_nothing_after": False
+                },
+                "pf": {
+                    "thm_type": "Proof",
+                    "thm_counter_incr": "0,0,0,1",
+                    "thm_name_overrides_thm_heading": True
+                }
+            },
+            "html_class": "md-dropdown",
+            "summary_html_class": "md-dropdown__summary mb-0"
+        },
+        thm_heading_config={
+            "html_class": "md-thm-heading",
+            "emph_html_class": "md-thm-heading__emph"
+        }
+    )
+])
+```
+
+## Markdown input:
+
+```md
+# Section {{1}}: this is theorem counter syntax from ThmsExtension()
+
+## Subsection {{0,1}}: Bees
+
+Here we begin our study of bees.
+
+
+
+\begin{thm}[the bee theorem]
+According to all known laws of aviation, there is no way that a bee should be able to fly.
+\end{thm}
+
+\begin{pf}
+Its wings are too small to get its fat little body off the ground.
+\end{pf}
+
+
+
+\begin{thm\*}{hidden thm name used as `id`; not real LaTeX syntax}
+Bees, of course, fly anyways.
+\end{thm\*}
+
+\begin{pf}[Proofs are configured to have titles override the heading]{hidden names are useless when there's already a name}
+Because bees don't care what humans think is impossible.
+\end{pf}
+
+
+
+\begin{exer}
+
+\begin{summary}
+Prove that this `summary` environment is common to all dropdown-based environments.
+\end{summary}
+
+Solution: by reading the documentation, of course!
+\end{exer}
+
+
+
+\begin{exer}
+All dropdowns initialized in `ThmsExtension()` have a default `summary` value of `thm_type`,
+so using dropdowns like `pf` and `exer` here without a `summary` block is also fine.
+
+Also, since there's no extra summary after the theorem heading of "Exercise", there is no punctuation
+(the colon; default punctuation is a period) since we set `"use_punct_if_nothing_after": False`.
+\end{exer}
+```
+
+## HTML output (prettified):
+
+```html
+<h1>Section 1: this is theorem counter syntax from ThmsExtension()</h1>
+<h2>Subsection 1.1: Bees</h2>
+
+<p>Here we begin our study of bees.</p>
+
+
+
+<div class="md-div md-thm">
+  <p>
+    <span class="md-thm-heading" id="the-bee-theorem"><span class="md-thm-heading__emph">Theorem 1.1.1</span> (the bee theorem)</span>.
+    According to all known laws of aviation, there is no way that a bee should be able to fly.
+  </p>
+</div>
+
+<details class="md-dropdown">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading"><span class="md-thm-heading__emph">Proof 1.1.1.1</span></span>.
+  </summary>
+  <div>
+    <p>Its wings are too small to get its fat little body off the ground.</p>
+  </div>
+</details>
+
+
+
+<div class="md-div md-thm">
+  <p>
+    <span class="md-thm-heading" id="hidden-thm-name-used-as-id-not-real-latex-syntax">
+      <span class="md-thm-heading__emph">Theorem</span>
+    </span>.
+    Bees, of course, fly anyways.
+  </p>
+</div>
+
+<details class="md-dropdown">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading" id="proofs-are-configured-to-have-titles-override-the-heading">
+      <span class="md-thm-heading__emph">Proofs are configured to have titles override the heading</span>
+    </span>.
+  </summary>
+  <div>
+    <p>Because bees don't care what humans think is impossible.</p>
+  </div>
+</details>
+
+
+
+<details class="md-dropdown md-exer">
+  <summary class="md-dropdown__summary mb-0">
+    <p>
+      <span class="md-thm-heading"><span class="md-thm-heading__emph">Exercise 1.1.2</span></span>:
+      Prove that this <code>summary</code> environment is common to all dropdown-based environments.
+    </p>
+  </summary>
+  <div>
+    <p>Solution: by reading the documentation, of course!</p>
+  </div>
+</details>
+
+
+
+<details class="md-dropdown md-exer">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading"><span class="md-thm-heading__emph">Exercise 1.1.3</span></span>
+  </summary>
+  <div>
+    <p>
+      All dropdowns initialized in <code>ThmsExtension()</code> have a default <code>summary</code> value of <code>thm_type</code>,
+      so using dropdowns like <code>pf</code> and <code>exer</code> here without a <code>summary</code> block is also fine.
+    </p>
+    <p>
+      Also, since there's no extra summary after the theorem heading of "Exercise", there is no punctuation
+      (the colon; default punctuation is a period) since we set <code>"use_punct_if_nothing_after": False</code>.
+    </p>
+  </div>
+</details>
+```
+
+## HTML example render:
+
+### Closed dropdowns:
+
+![example render (closed dropdowns)](https://github.com/user-attachments/assets/6ed34a55-ba7f-48c0-9c82-10efd7cb53d2)
+
+### Open dropdowns:
+
+![example render (open dropdowns)](https://github.com/user-attachments/assets/92410977-a048-4e4d-b425-84b550d6699b)

markdown_environments-1.0.0/README.md

@@ -0,0 +1,227 @@
+# Markdown-Environments
+
+Replicating amsthm features and syntax in Markdown so you can publish mathematical papers in HTML—because what mathematician *hasn't* tried to publish to the very reputable journal called *Their Janky Flask Personal Site That No One Will Ever See*?
+
+This Python-Markdown extension uses LaTeX-like syntax
+```
+\begin{...}
+...
+\end{...}
+```
+to create enviroments such as captioned figures, general-purpose `<div>`s, dropdowns, and user-defined LaTeX-style theorems that can be styled with attached HTML `class`es.
+
+## Installation
+
+```
+pip install markdown-environments
+```
+
+## Available Environments
+
+- `\begin{captioned_figure}`: figures with captions
+- `\begin{cited_blockquote}`: blockquotes with quote attribution
+- User-defined environments wrapped in general-purpose `<div>`s to style to your heart's content
+- User-defined environments formatted as `<details>` and `<summary>` dropdowns
+- User-defined LaTeX theorem environments with customizable:
+    - Theorem counters
+    - Heading punctuation
+    - Linkable `id`s by theorem name
+
+## Further Reading
+
+Full documentation and detailed usage examples can be found [here](https://python-markdown-environments.readthedocs.io).
+
+<!-- example usage -->
+
+# Example Usage
+
+## Backend:
+
+```py
+import markdown
+from markdown_environments import ThmsExtension
+
+input_text = ...
+output_text = markdown.markdown(input_text, extensions=[
+    ThmsExtension(
+        div_config={
+            "types": {
+                "thm": {
+                    "thm_type": "Theorem",
+                    "html_class": "md-thm",
+                    "thm_counter_incr": "0,0,1"
+                },
+                r"thm\\\*": {
+                    "thm_type": "Theorem",
+                    "html_class": "md-thm"
+                }
+            },
+            "html_class": "md-div"
+        },
+        dropdown_config={
+            "types": {
+                "exer": {
+                    "thm_type": "Exercise",
+                    "html_class": "md-exer",
+                    "thm_counter_incr": "0,0,1",
+                    "thm_punct": ":",
+                    "use_punct_if_nothing_after": False
+                },
+                "pf": {
+                    "thm_type": "Proof",
+                    "thm_counter_incr": "0,0,0,1",
+                    "thm_name_overrides_thm_heading": True
+                }
+            },
+            "html_class": "md-dropdown",
+            "summary_html_class": "md-dropdown__summary mb-0"
+        },
+        thm_heading_config={
+            "html_class": "md-thm-heading",
+            "emph_html_class": "md-thm-heading__emph"
+        }
+    )
+])
+```
+
+## Markdown input:
+
+```md
+# Section {{1}}: this is theorem counter syntax from ThmsExtension()
+
+## Subsection {{0,1}}: Bees
+
+Here we begin our study of bees.
+
+
+
+\begin{thm}[the bee theorem]
+According to all known laws of aviation, there is no way that a bee should be able to fly.
+\end{thm}
+
+\begin{pf}
+Its wings are too small to get its fat little body off the ground.
+\end{pf}
+
+
+
+\begin{thm\*}{hidden thm name used as `id`; not real LaTeX syntax}
+Bees, of course, fly anyways.
+\end{thm\*}
+
+\begin{pf}[Proofs are configured to have titles override the heading]{hidden names are useless when there's already a name}
+Because bees don't care what humans think is impossible.
+\end{pf}
+
+
+
+\begin{exer}
+
+\begin{summary}
+Prove that this `summary` environment is common to all dropdown-based environments.
+\end{summary}
+
+Solution: by reading the documentation, of course!
+\end{exer}
+
+
+
+\begin{exer}
+All dropdowns initialized in `ThmsExtension()` have a default `summary` value of `thm_type`,
+so using dropdowns like `pf` and `exer` here without a `summary` block is also fine.
+
+Also, since there's no extra summary after the theorem heading of "Exercise", there is no punctuation
+(the colon; default punctuation is a period) since we set `"use_punct_if_nothing_after": False`.
+\end{exer}
+```
+
+## HTML output (prettified):
+
+```html
+<h1>Section 1: this is theorem counter syntax from ThmsExtension()</h1>
+<h2>Subsection 1.1: Bees</h2>
+
+<p>Here we begin our study of bees.</p>
+
+
+
+<div class="md-div md-thm">
+  <p>
+    <span class="md-thm-heading" id="the-bee-theorem"><span class="md-thm-heading__emph">Theorem 1.1.1</span> (the bee theorem)</span>.
+    According to all known laws of aviation, there is no way that a bee should be able to fly.
+  </p>
+</div>
+
+<details class="md-dropdown">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading"><span class="md-thm-heading__emph">Proof 1.1.1.1</span></span>.
+  </summary>
+  <div>
+    <p>Its wings are too small to get its fat little body off the ground.</p>
+  </div>
+</details>
+
+
+
+<div class="md-div md-thm">
+  <p>
+    <span class="md-thm-heading" id="hidden-thm-name-used-as-id-not-real-latex-syntax">
+      <span class="md-thm-heading__emph">Theorem</span>
+    </span>.
+    Bees, of course, fly anyways.
+  </p>
+</div>
+
+<details class="md-dropdown">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading" id="proofs-are-configured-to-have-titles-override-the-heading">
+      <span class="md-thm-heading__emph">Proofs are configured to have titles override the heading</span>
+    </span>.
+  </summary>
+  <div>
+    <p>Because bees don't care what humans think is impossible.</p>
+  </div>
+</details>
+
+
+
+<details class="md-dropdown md-exer">
+  <summary class="md-dropdown__summary mb-0">
+    <p>
+      <span class="md-thm-heading"><span class="md-thm-heading__emph">Exercise 1.1.2</span></span>:
+      Prove that this <code>summary</code> environment is common to all dropdown-based environments.
+    </p>
+  </summary>
+  <div>
+    <p>Solution: by reading the documentation, of course!</p>
+  </div>
+</details>
+
+
+
+<details class="md-dropdown md-exer">
+  <summary class="md-dropdown__summary mb-0">
+    <span class="md-thm-heading"><span class="md-thm-heading__emph">Exercise 1.1.3</span></span>
+  </summary>
+  <div>
+    <p>
+      All dropdowns initialized in <code>ThmsExtension()</code> have a default <code>summary</code> value of <code>thm_type</code>,
+      so using dropdowns like <code>pf</code> and <code>exer</code> here without a <code>summary</code> block is also fine.
+    </p>
+    <p>
+      Also, since there's no extra summary after the theorem heading of "Exercise", there is no punctuation
+      (the colon; default punctuation is a period) since we set <code>"use_punct_if_nothing_after": False</code>.
+    </p>
+  </div>
+</details>
+```
+
+## HTML example render:
+
+### Closed dropdowns:
+
+![example render (closed dropdowns)](https://github.com/user-attachments/assets/6ed34a55-ba7f-48c0-9c82-10efd7cb53d2)
+
+### Open dropdowns:
+
+![example render (open dropdowns)](https://github.com/user-attachments/assets/92410977-a048-4e4d-b425-84b550d6699b)

markdown_environments-1.0.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = ./
+BUILDDIR      = _build/
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

markdown_environments-1.0.0/docs/_static/css/custom.css

@@ -0,0 +1,17 @@
+h1 {
+    font-size: 2.25em;
+}
+
+h2 {
+    font-size: 1.75em;
+}
+
+.rst-content p.rubric,
+.rst-content dl dt {
+    margin-bottom: 12px !important;
+    border-left: 3px solid #ccc !important;
+    background: #f0f0f0;
+    padding: 0.25em;
+    color: #404040 !important;
+    font-size: 1.15em;
+}

markdown_environments-1.0.0/docs/api.rst

@@ -0,0 +1,38 @@
+API Reference
+=============
+
+.. automodule:: markdown_environments
+
+..
+    for making sure sphinx can find the classes
+.. currentmodule:: markdown_environments
+
+Captioned Figure
+----------------
+
+.. autoclass:: CaptionedFigureExtension()
+    :members: __init__
+
+Cited Blockquote
+----------------
+
+.. autoclass:: CitedBlockquoteExtension()
+    :members: __init__
+
+Div
+---
+
+.. autoclass:: DivExtension()
+    :members: __init__
+
+Dropdown
+--------
+
+.. autoclass:: DropdownExtension()
+    :members: __init__
+
+Thms
+----
+
+.. autoclass:: ThmsExtension()
+    :members: __init__