markwright 0.1.0__py3-none-any.whl

markwright/twitter.py

@@ -0,0 +1,187 @@
+# ABOUTME: Twitter embed extension for Python-Markdown.
+# Converts [twitter URL flags...] syntax to Twitter blockquote embeds with script injection.
+
+from __future__ import annotations
+
+import html
+import re
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.postprocessors import Postprocessor
+from markdown.preprocessors import Preprocessor
+
+from markwright._util import URL_SCHEME_WWW_PREFIX
+
+# Scheme, "www.", and the twitter.com/x.com host are all optional, and when
+# present must be followed by a "/", so inputs from a bare "user/status/id"
+# up to a full "https://www.twitter.com/user/status/id" all match. Ported
+# verbatim from upstream twitter.js's URL-matching grammar.
+TWITTER_RE = re.compile(
+    r"^\[twitter\s+(?:(?:" + URL_SCHEME_WWW_PREFIX + r"(?:twitter|x)\.com)?/)?(\w+)/status/(\d+)"
+    r"((?:\s+(?:light|dark|left|center|right|\d+))*)\]$"
+)
+
+TWITTER_MIN_WIDTH = 250
+TWITTER_MAX_WIDTH = 550
+TWITTER_DEFAULT_WIDTH = 550
+
+TWITTER_SIGNATURE = 'class="twitter-tweet"'
+
+TWITTER_SCRIPT = '<script async defer src="https://platform.twitter.com/widgets.js"></script>'
+
+
+def _parse_twitter_flags(raw_flags: str) -> dict[str, str | int]:
+    """Parse space-separated Twitter flags into a settings dictionary.
+
+    :param raw_flags: Raw space-separated flags string.
+    :returns: Dictionary with theme, alignment, and width settings.
+    """
+    flags = raw_flags.split()
+
+    theme = "dark" if "dark" in flags else "light"
+
+    alignment = "center"
+    for align_option in ("left", "right", "center"):
+        if align_option in flags:
+            alignment = align_option
+            break
+
+    width = TWITTER_DEFAULT_WIDTH
+    for flag in flags:
+        if flag.isdigit():
+            width = max(TWITTER_MIN_WIDTH, min(TWITTER_MAX_WIDTH, int(flag)))
+            break
+
+    return {
+        "theme": theme,
+        "alignment": alignment,
+        "width": width,
+    }
+
+
+def _render_match(line: str) -> str | None:
+    """Build the Twitter embed HTML for a standalone embed line.
+
+    :param line: A single source line.
+    :returns: The embed HTML if the line is a Twitter embed, else ``None``.
+    """
+    twitter_match = TWITTER_RE.match(line.strip())
+    if not twitter_match:
+        return None
+
+    user = twitter_match.group(1)
+    status_id = twitter_match.group(2)
+    raw_flags = twitter_match.group(3).strip()
+    settings = _parse_twitter_flags(raw_flags)
+
+    # Canonicalize to twitter.com
+    canonical_url = f"https://twitter.com/{user}/status/{status_id}"
+    escaped_url = html.escape(canonical_url)
+    escaped_user = html.escape(user)
+
+    theme = settings["theme"]
+    alignment = settings["alignment"]
+    width = settings["width"]
+
+    align_attr = f' align="{alignment}"' if alignment != "center" else ""
+
+    return (
+        f'<div class="twitter"{align_attr}>\n'
+        f'    <blockquote class="twitter-tweet" data-dnt="true"'
+        f' data-width="{width}" data-theme="{theme}">\n'
+        f'        <a href="{escaped_url}">View tweet by @{escaped_user}</a>\n'
+        f"    </blockquote>\n"
+        f"</div>"
+    )
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone Twitter embed lines to embed HTML in raw source.
+
+    Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
+    HTML inline without any Python-Markdown stash placeholder.
+
+    :param text: The source text.
+    :returns: The text with standalone Twitter embeds replaced by HTML.
+    """
+    return "\n".join(_render_match(line) or line for line in text.split("\n"))
+
+
+def apply_html(rendered_html: str, warnings: list[str] | None = None) -> str:
+    """Inject the Twitter widgets script once if a Twitter embed is present.
+
+    Used by the ``mw post`` CLI stage and the in-process postprocessor. The
+    script is appended only when the Twitter class signature is present and the
+    script is not already injected, so the transform is idempotent.
+
+    :param rendered_html: Rendered HTML content.
+    :param warnings: Optional warnings list; unused (signature injection never warns).
+    :returns: HTML with the Twitter script appended if needed.
+    """
+    if TWITTER_SIGNATURE in rendered_html and TWITTER_SCRIPT not in rendered_html:
+        return rendered_html + "\n" + TWITTER_SCRIPT
+    return rendered_html
+
+
+class TwitterPreprocessor(Preprocessor):
+    """Replace [twitter ...] lines with Twitter embed HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing Twitter embed syntax with HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with Twitter embeds replaced by HTML.
+        """
+        output: list[str] = []
+        for line in lines:
+            embed_html = _render_match(line)
+            if embed_html is not None:
+                output.append(self.md.htmlStash.store(embed_html))
+            else:
+                output.append(line)
+        return output
+
+
+class TwitterPostprocessor(Postprocessor):
+    """Append the Twitter widgets script tag once if any embeds are present.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, text: str) -> str:
+        """Append the script tag if a Twitter embed signature is present.
+
+        :param text: Rendered HTML content.
+        :returns: HTML with Twitter script appended if needed.
+        """
+        return apply_html(text)
+
+
+class TwitterExtension(Extension):
+    """Python-Markdown extension for Twitter embeds.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the Twitter preprocessor and postprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = TwitterPreprocessor(md)
+        postprocessor = TwitterPostprocessor(md)
+        md.preprocessors.register(preprocessor, "do-twitter", 20)
+        md.postprocessors.register(postprocessor, "do-twitter-script", 15)
+
+
+def makeExtension(**kwargs: object) -> TwitterExtension:
+    """Create and return the TwitterExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured TwitterExtension.
+    """
+    return TwitterExtension(**kwargs)

markwright/youtube.py

@@ -0,0 +1,106 @@
+# ABOUTME: YouTube embed extension for Python-Markdown.
+# Converts [youtube ID height width] syntax to responsive iframe embeds.
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+
+from markwright._util import reduce_fraction
+
+YOUTUBE_RE = re.compile(r"^\[youtube (\S+?)(?:\s+(-?\d+))?(?:\s+(-?\d+))?\]$")
+
+DEFAULT_HEIGHT = 270
+DEFAULT_WIDTH = 480
+
+
+def _render_match(line: str) -> str | None:
+    """Build the iframe HTML for a standalone YouTube embed line.
+
+    :param line: A single source line.
+    :returns: The iframe HTML if the line is a YouTube embed, else ``None``.
+    """
+    youtube_match = YOUTUBE_RE.match(line.strip())
+    if not youtube_match:
+        return None
+
+    video_id = youtube_match.group(1)
+    height = int(youtube_match.group(2)) if youtube_match.group(2) else DEFAULT_HEIGHT
+    width = int(youtube_match.group(3)) if youtube_match.group(3) else DEFAULT_WIDTH
+    if height <= 0 or width <= 0:
+        height, width = DEFAULT_HEIGHT, DEFAULT_WIDTH
+
+    encoded_id = urllib.parse.quote(video_id, safe="")
+    aspect_width, aspect_height = reduce_fraction(width, height)
+    aspect_ratio = f"{aspect_width}/{aspect_height}"
+
+    return (
+        f'<iframe src="https://www.youtube.com/embed/{encoded_id}"'
+        f' class="youtube" height="{height}" width="{width}"'
+        f' style="aspect-ratio: {aspect_ratio}" frameborder="0" allowfullscreen>\n'
+        f'    <a href="https://www.youtube.com/watch?v={encoded_id}"'
+        f' target="_blank">View YouTube video</a>\n'
+        f"</iframe>"
+    )
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone YouTube embed lines to iframe HTML in raw source.
+
+    Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
+    HTML inline without any Python-Markdown stash placeholder.
+
+    :param text: The source text.
+    :returns: The text with standalone YouTube embeds replaced by iframe HTML.
+    """
+    return "\n".join(_render_match(line) or line for line in text.split("\n"))
+
+
+class YouTubePreprocessor(Preprocessor):
+    """Replace [youtube ...] lines with responsive iframe HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing YouTube embed syntax with iframe HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with YouTube embeds replaced by HTML.
+        """
+        output: list[str] = []
+        for line in lines:
+            iframe_html = _render_match(line)
+            if iframe_html is not None:
+                output.append(self.md.htmlStash.store(iframe_html))
+            else:
+                output.append(line)
+        return output
+
+
+class YouTubeExtension(Extension):
+    """Python-Markdown extension for YouTube video embeds.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the YouTube preprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = YouTubePreprocessor(md)
+        md.preprocessors.register(preprocessor, "do-youtube", 20)
+
+
+def makeExtension(**kwargs: object) -> YouTubeExtension:
+    """Create and return the YouTubeExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured YouTubeExtension.
+    """
+    return YouTubeExtension(**kwargs)

markwright-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: markwright
+Version: 0.1.0
+Summary: Python-Markdown extensions ported from DigitalOcean's do-markdownit
+Keywords: markdown,python-markdown,do-markdownit,mkdocs,hugo
+Author: Mason Egger
+Author-email: Mason Egger <mason@masonegger.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSE-Apache-2.0
+License-File: NOTICE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Dist: markdown>=3.4
+Requires-Dist: pymdown-extensions>=10.5
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/MasonEgger/markwright
+Project-URL: Repository, https://github.com/MasonEgger/markwright
+Project-URL: Documentation, https://masonegger.github.io/markwright/
+Description-Content-Type: text/markdown
+
+# markwright
+
+A Python port of DigitalOcean's [`do-markdownit`](https://github.com/digitalocean/do-markdownit) JavaScript library.
+
+These are [Python-Markdown](https://python-markdown.github.io/) extensions that bring DigitalOcean's markdown syntax (highlighted text, labeled code fences, and a set of media embeds) to any tool built on Python-Markdown, including [MkDocs](https://www.mkdocs.org/), Flask, or a plain script.
+The port maintains compatibility with the original `do-markdownit` HTML output, so rendered pages match what DigitalOcean produces.
+A bundled command-line tool, `mw`, runs the same extensions as pre and post filters around any renderer, so the syntax also works in toolchains that are not built on Python-Markdown, like Hugo.
+
+Full documentation and a live demo: https://masonegger.github.io/markwright/
+
+## Features
+
+Each extension is standalone and can be loaded on its own or alongside the others.
+
+- **Highlight** wraps `<^>text<^>` in `<mark>`, and works inside inline code and fenced code blocks where `==text==` cannot reach.
+- **Fence** adds labels, secondary labels, environment classes, and command-line prefixes (line numbers, `$`/`#` prompts, custom prefixes) to code blocks.
+- **YouTube** turns `[youtube ID]` into a responsive iframe embed.
+- **CodePen** embeds a pen with theme, default-tab, and layout options.
+- **Twitter** embeds a tweet with theme and alignment options.
+- **Instagram** embeds a post with caption and alignment options.
+- **Slideshow** builds an image slideshow with navigation arrows.
+- **Image Compare** renders two images with a draggable before/after slider.
+
+## Installation
+
+```bash
+uv add markwright
+```
+
+or
+
+```bash
+pip install markwright
+```
+
+To work against a local checkout, install it editable:
+
+```bash
+uv add --editable ../markwright
+```
+
+## Usage
+
+### With MkDocs
+
+Add the extensions to `mkdocs.yml`.
+Load `markwright.fence` after `pymdownx.superfences` and `pymdownx.highlight` so the code-block HTML is in the shape the fence postprocessor expects.
+
+```yaml
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      pygments_lang_class: true
+  - markwright.highlight
+  - markwright.fence:
+      allowed_environments:
+        - local
+        - second
+        - third
+  - markwright.youtube
+  - markwright.codepen
+  - markwright.twitter
+  - markwright.instagram
+  - markwright.slideshow
+  - markwright.image_compare
+```
+
+### Standalone
+
+The extensions work with Python-Markdown directly, so you can use them in any Python program.
+
+```python
+import markdown
+
+md = markdown.Markdown(extensions=[
+    "pymdownx.superfences",
+    "pymdownx.highlight",
+    "markwright.highlight",
+    "markwright.fence",
+    "markwright.youtube",
+    "markwright.codepen",
+    "markwright.twitter",
+    "markwright.instagram",
+    "markwright.slideshow",
+    "markwright.image_compare",
+])
+
+html = md.convert("This has a <^>highlighted word<^> in it.")
+print(html)
+```
+
+Load only what you need:
+
+```python
+import markdown
+
+# Just YouTube embeds
+md = markdown.Markdown(extensions=["markwright.youtube"])
+html = md.convert("[youtube dQw4w9WgXcQ]")
+```
+
+The fence extension expects `pymdownx.superfences` and `pymdownx.highlight` to be loaded too.
+Without them the preprocessor still extracts directives, but the code-block HTML may not match what the postprocessor rewrites.
+
+## Command-Line Interface (`mw`)
+
+For a toolchain that is not built on Python-Markdown, the `mw` command runs the same extensions as a pair of Unix filters around any renderer: a pre stage on the Markdown source, and a post stage on the rendered HTML.
+
+```bash
+mw pre < in.md | your-renderer | mw post > out.html
+```
+
+- `mw pre` expands the embeds and extracts fence directives into an `mw-fence` comment.
+- `mw post` applies the fence styling, resolves the highlights, and injects each embed script once.
+- `mw render` runs the full pipeline in one shot for callers without their own renderer.
+- `mw list` prints every extension and the stages it provides.
+
+Your renderer must pass raw HTML and HTML comments through.
+Hugo is a worked, tested example: see the [Hugo guide](https://masonegger.github.io/markwright/integrations/hugo/).
+The full command and flag reference is in the [CLI docs](https://masonegger.github.io/markwright/cli/).
+
+## Syntax at a Glance
+
+````text
+Highlight:       <^>important<^>
+
+Fenced code with a label and command prompts:
+    ```command
+    [label deploy.sh]
+    ssh root@server
+    apt update
+    ```
+
+YouTube:         [youtube dQw4w9WgXcQ]
+                 [youtube dQw4w9WgXcQ 360 640]
+CodePen:         [codepen MattCowley vwPzeX]
+                 [codepen MattCowley vwPzeX dark css]
+Twitter:         [twitter https://twitter.com/github/status/1234567890]
+Instagram:       [instagram https://www.instagram.com/p/CkQuv3_LRgS]
+Slideshow:       [slideshow https://picsum.photos/id/10/480/270 https://picsum.photos/id/20/480/270]
+Image Compare:   [compare before.jpg after.jpg]
+````
+
+See the [extension docs](https://masonegger.github.io/markwright/) for every flag and the exact HTML each one produces.
+
+## Development
+
+This project uses [`uv`](https://docs.astral.sh/uv/) and [`just`](https://github.com/casey/just).
+
+```bash
+just install           # uv sync
+just test              # unit tests, 100% line + branch coverage
+just test-integration  # end-to-end Hugo pipeline test (needs hugo)
+just lint              # ruff check + ruff format --check
+just typecheck         # mypy --strict
+just check             # test + lint + typecheck
+just docs-serve        # serve the docs site at localhost:8000
+```
+
+`just check` must pass before a change is complete.
+The tooling bar is strict: `mypy --strict`, a clean `ruff`, and full test coverage.
+
+## License
+
+markwright is released under the [MIT License](LICENSE).
+
+It is a port of [`do-markdownit`](https://github.com/digitalocean/do-markdownit) by DigitalOcean, which is licensed under the Apache License 2.0.
+See the [NOTICE](NOTICE) file for attribution details.

markwright-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+markwright/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markwright/_util.py,sha256=BI3Ams_h52bPjUnDWicSeacXULmxpNZmQIDj9st9ZQU,1279
+markwright/cli.py,sha256=u-xX6_hiVh_NjNyuEhBiH8b0uftw4gRynluA_lOY4Fo,5565
+markwright/codepen.py,sha256=R4Wo8y2znGUZuREUo-VZVIxJ2xePk30vqi1vs6lV92c,6815
+markwright/fence.py,sha256=MQVYAFM-alFIJAEnRflyxs5HeKFoV73ZHrDIIzrUuF4,19768
+markwright/highlight.py,sha256=Bzgz8-RFmUQ2EIEwJiDQ9n80yzRqwMZNqHh_DnhWzbs,7648
+markwright/image_compare.py,sha256=EID0oa8T-uNs35KBq5WwKhS640GJmUs3AM2CTLM9Xzo,4810
+markwright/instagram.py,sha256=2rJwUpqejJdOoXopLvCTATiSOXrFDPbPGaX_qIF11ZU,6644
+markwright/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markwright/registry.py,sha256=6meSIct5DdkVV_t3cX0waYit_YmJ-IRh2jJiOIgaLKc,5935
+markwright/slideshow.py,sha256=rv25PkhoYTADLuIAJ_UWU3bMm1_kFrQermAbPxI7iWg,4841
+markwright/twitter.py,sha256=t8yzuF5rr_mz4fDmDok0v2FMlFb6_yeocR1eNbwM8qc,6261
+markwright/youtube.py,sha256=-GaDUZneA1Jji66yZvc1HmK58VhHwBxv_O00Xrkd8i0,3535
+markwright-0.1.0.dist-info/licenses/LICENSE,sha256=2lCfnjZ3jo5wTPiXG_2XesGsPbfJyhAYlCd3kTmYCio,1068
+markwright-0.1.0.dist-info/licenses/LICENSE-Apache-2.0,sha256=DlD_JqT3u3kroA5EzJNq_Bl5b7hSImEASqHAVdBIckg,10760
+markwright-0.1.0.dist-info/licenses/NOTICE,sha256=iANynyRpH3OWLtlIHOFDUxn304VgEobUKKexJy4kYBs,1204
+markwright-0.1.0.dist-info/WHEEL,sha256=_d8F1e7SqtoW6CDj4Gi8lFC26a_7I17R7zPLCKTp4Fg,81
+markwright-0.1.0.dist-info/entry_points.txt,sha256=b2GIDio68udBvjKs86sxzirrQlwaCxPm6jWAk7yMMR0,44
+markwright-0.1.0.dist-info/METADATA,sha256=9QXUMFUPnBINSRsF-KlX8cvxLZ2Ajpoh1wtwFMzeuRs,7058
+markwright-0.1.0.dist-info/RECORD,,

markwright-0.1.0.dist-info/WHEEL

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

markwright-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mw = markwright.cli:main
+

markwright-0.1.0.dist-info/licenses/LICENSE

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