Skip to content

Commit

Permalink
Add support for GitHub syntax of alerts/admonitions
Browse files Browse the repository at this point in the history
  • Loading branch information
hunyadi committed Sep 10, 2024
1 parent 6a5f41f commit 9716a9b
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 0 deletions.
54 changes: 54 additions & 0 deletions md2conf/converter.py
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,48 @@ def _transform_admonition(self, elem: ET._Element) -> ET._Element:
*content,
)

def _transform_alert(self, elem: ET._Element) -> ET._Element:
"""
Creates an info, tip, note or warning panel from a GitHub alert.
Transforms
[GitHub alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) # noqa: E501 # no way to make this link shorter
syntax into one of the Confluence structured macros *info*, *tip*, *note*, or *warning*.
"""

content = elem[0]
pattern = re.compile(r"^\[!([A-Z]+)\]\s*")
match = pattern.match(content.text or "")
if match is None:
raise DocumentError("not an alert")
alert = match.group(1)

if alert == "NOTE":
class_name = "note"
elif alert == "TIP":
class_name = "tip"
elif alert == "IMPORTANT":
class_name = "tip"
elif alert == "WARNING":
class_name = "warning"
elif alert == "CAUTION":
class_name = "warning"
else:
raise DocumentError(f"unsupported alert: {alert}")

for e in elem:
self.visit(e)

content.text = pattern.sub("", content.text, count=1)
return AC(
"structured-macro",
{
ET.QName(namespaces["ac"], "name"): class_name,
ET.QName(namespaces["ac"], "schema-version"): "1",
},
AC("rich-text-body", {}, *list(elem)),
)

def _transform_section(self, elem: ET._Element) -> ET._Element:
"""
Creates a collapsed section.
Expand Down Expand Up @@ -569,6 +611,18 @@ def transform(self, child: ET._Element) -> Optional[ET._Element]:
elif child.tag == "div" and "admonition" in child.attrib.get("class", ""):
return self._transform_admonition(child)

# Alerts in GitHub
# <blockquote>
# <p>[!TIP] ...</p>
# </blockquote>
elif (
child.tag == "blockquote"
and len(child) > 0
and child[0].tag == "p"
and child[0].text.startswith("[!")
):
return self._transform_alert(child)

# <details markdown="1">
# <summary>...</summary>
# ...
Expand Down
28 changes: 28 additions & 0 deletions tests/source/alert.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<!-- confluence-page-id: 00000000000 -->

## Alerts

Note:

> [!NOTE]
> Useful information that users should know, even when skimming content.
Tip:

> [!TIP]
> Helpful advice for doing things better or more easily.
Important:

> [!IMPORTANT]
> Key information users need to know to achieve their goal.
Warning:

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
Caution:

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
36 changes: 36 additions & 0 deletions tests/target/alert.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<ac:structured-macro ac:name="info" ac:schema-version="1">
<ac:rich-text-body>
<p>This page has been generated with a tool.</p>
</ac:rich-text-body>
</ac:structured-macro>
<h2>Alerts</h2>
<p>Note:</p>
<ac:structured-macro ac:name="note" ac:schema-version="1">
<ac:rich-text-body>
<p>Useful information that users should know, even when skimming content.</p>
</ac:rich-text-body>
</ac:structured-macro>
<p>Tip:</p>
<ac:structured-macro ac:name="tip" ac:schema-version="1">
<ac:rich-text-body>
<p>Helpful advice for doing things better or more easily.</p>
</ac:rich-text-body>
</ac:structured-macro>
<p>Important:</p>
<ac:structured-macro ac:name="tip" ac:schema-version="1">
<ac:rich-text-body>
<p>Key information users need to know to achieve their goal.</p>
</ac:rich-text-body>
</ac:structured-macro>
<p>Warning:</p>
<ac:structured-macro ac:name="warning" ac:schema-version="1">
<ac:rich-text-body>
<p>Urgent info that needs immediate user attention to avoid problems.</p>
</ac:rich-text-body>
</ac:structured-macro>
<p>Caution:</p>
<ac:structured-macro ac:name="warning" ac:schema-version="1">
<ac:rich-text-body>
<p>Advises about risks or negative outcomes of certain actions.</p>
</ac:rich-text-body>
</ac:structured-macro>

0 comments on commit 9716a9b

Please sign in to comment.