Improve markdown rendering (fix #6)

Author: object-Object

.vscode/settings.json

@@ -17,6 +17,7 @@
         { "name": "pydantic", "depth": 2 },
         { "name": "discord", "depth": 3 },
         { "name": "sqlalchemy", "depth": 2 },
+        { "name": "marko", "depth": 2 },
     ],
     "sqltools.useNodeRuntime": true,
     "sqltools.connections": [

bot/pyproject.toml

@@ -22,6 +22,7 @@ dependencies = [
     "pylette>=4.0.0",
     "humanize>=4.13.0",
     "babel>=2.17.0",
+    "marko>=2.2.0",
 ]
 
 [tool.rye]

bot/src/ghutils/ui/embeds/commits.py

@@ -9,7 +9,7 @@
 from githubkit.exception import GitHubException
 from githubkit.rest import Commit, SimpleUser
 
-from ghutils.utils.discord.embeds import set_embed_author
+from ghutils.utils.discord.embeds import set_embed_author, truncate_markdown_description
 from ghutils.utils.github import (
     CommitCheckState,
     RepositoryName,
@@ -35,7 +35,7 @@ async def create_commit_embed(
     description = None
     if "\n" in message:
         message, description = message.split("\n", maxsplit=1)
-        description = truncate_str(description.strip(), 200)
+        description = truncate_markdown_description(description)
 
     embed = Embed(
         title=truncate_str(f"[{short_sha}] {message}", 256),

bot/src/ghutils/ui/embeds/issues.py

@@ -9,7 +9,7 @@
 from githubkit.rest import Issue, IssuePropPullRequest, PullRequest
 
 from ghutils.ui.components.visibility import MessageContents
-from ghutils.utils.discord.embeds import set_embed_author
+from ghutils.utils.discord.embeds import set_embed_author, truncate_markdown_description
 from ghutils.utils.discord.references import IssueReference, IssueReferenceTransformer
 from ghutils.utils.github import IssueState, PullRequestState, RepositoryName
 from ghutils.utils.strings import truncate_str
@@ -42,7 +42,7 @@ def create_issue_embed(
     )
 
     if issue.body and add_body:
-        embed.description = truncate_str(issue.body, 200)
+        embed.description = truncate_markdown_description(issue.body)
 
     if issue.user:
         set_embed_author(embed, issue.user)

bot/src/ghutils/ui/embeds/releases.py

@@ -7,7 +7,7 @@
 from discord.ui import Button, Item
 from githubkit.rest import Release
 
-from ghutils.utils.discord.embeds import set_embed_author
+from ghutils.utils.discord.embeds import set_embed_author, truncate_markdown_description
 from ghutils.utils.github import ReleaseState, RepositoryName, get_reactions_by_emoji
 from ghutils.utils.strings import truncate_str
 
@@ -57,7 +57,7 @@ def create_release_embed(
         )
 
     if release.body and add_body:
-        embed.description = truncate_str(release.body, 200)
+        embed.description = truncate_markdown_description(release.body)
 
     if release.author:
         set_embed_author(embed, release.author)

bot/src/ghutils/utils/discord/embeds.py

@@ -1,8 +1,14 @@
 from __future__ import annotations
 
+import re
+from typing import overload
+
 from discord import Embed
 from githubkit.rest import SimpleUser
 
+from ghutils.utils.markdown import reflow_markdown
+from ghutils.utils.strings import truncate_str
+
 
 def set_embed_author(embed: Embed, user: SimpleUser):
     embed.set_author(
@@ -11,3 +17,35 @@ def set_embed_author(embed: Embed, user: SimpleUser):
         icon_url=user.avatar_url,
     )
     return embed
+
+
+_NEWLINE_HEADING_PATTERN = re.compile(r"(\n|^)\n+(#+ +\S)")
+
+
+@overload
+def truncate_markdown_description(text: str, limit: int = ...) -> str: ...
+
+
+@overload
+def truncate_markdown_description(text: str | None, limit: int = ...) -> str | None: ...
+
+
+def truncate_markdown_description(text: str | None, limit: int = 256) -> str | None:
+    if text is None:
+        return None
+
+    text = reflow_markdown(text)
+    text = _NEWLINE_HEADING_PATTERN.sub(r"\1\2", text)
+    text = text.strip()
+
+    if len(text) <= limit:
+        return text
+
+    # truncate the string at the first whitespace character after overflowing
+    # TODO: would it be better to truncate before instead?
+    i = 0
+    for c in text:
+        if i >= limit and c.isspace():
+            break
+        i += 1
+    return text[:i] + "..."

bot/src/ghutils/utils/markdown.py

@@ -0,0 +1,35 @@
+import dataclasses
+import re
+from typing import override
+
+from marko import Markdown
+from marko.block import HTMLBlock
+from marko.ext.gfm import GFM
+from marko.inline import InlineHTML
+from marko.md_renderer import MarkdownRenderer
+
+
+class DiscordMarkdownRenderer(MarkdownRenderer):
+    @override
+    def render_html_block(self, element: HTMLBlock) -> str:
+        return _strip_html_comments(super().render_html_block(element))
+
+    @override
+    def render_inline_html(self, element: InlineHTML) -> str:
+        return _strip_html_comments(super().render_inline_html(element))
+
+
+_HTML_COMMENT_PATTERN = re.compile(r"<!--.*?-->")
+
+
+def _strip_html_comments(text: str) -> str:
+    return _HTML_COMMENT_PATTERN.sub("", text)
+
+
+def reflow_markdown(text: str) -> str:
+    md = Markdown(
+        renderer=DiscordMarkdownRenderer,
+        # don't render as GFM
+        extensions=[dataclasses.replace(GFM, renderer_mixins=[])],
+    )
+    return md.convert(text)

requirements-dev.lock

@@ -136,6 +136,8 @@ jsii==1.103.1
     # via constructs
 markdown-it-py==3.0.0
     # via rich
+marko==2.2.0
+    # via ghutils-bot
 markupsafe==2.1.5
     # via jinja2
 mdurl==0.1.2

requirements.lock

@@ -128,6 +128,8 @@ jsii==1.103.1
     # via constructs
 markdown-it-py==3.0.0
     # via rich
+marko==2.2.0
+    # via ghutils-bot
 markupsafe==2.1.5
     # via jinja2
 mdurl==0.1.2