Replace `markdown2` with `markdown` and `python-frontmatter`.

This allows us to properly escape codeblocks within markdown, permalink
to headers on a page, and decouples getting metadata from a file and
getting generated HTML from the Markdown content.

6 files changed, 106 insertions, 35 deletions

diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md
index 8967e7da..12969ba2 100644
--- a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md
+++ b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md
@@ -69,18 +69,75 @@ You can learn more about Markdown metadata [here](https://github.com/trentm/pyth
 
 Apart from standard Markdown, certain additions are available:
 
+### Abbreviations
+HTML `<abbr>` tags can be used in markdown using this format:
+
+**Markdown:**
+```nohighlight
+This website is HTML generated from YAML and Markdown.
+
+*[HTML]: Hyper Text Markup Language
+*[YAML]: YAML Ain't Markup Language
+```
+
+**Output:**
+
+This website is <abbr title="Hyper Text Markup Language">HTML</abbr>
+generated from <abbr title="YAML Ain't Markup Language">YAML</abbr> and Markdown.
+
+---
+
+### Footnotes
+**Markdown:**
+```nohighlight
+This footnote[^1] links to the bottom[^custom_label] of the page[^3].
+
+[^1]: Footnote labels start with a caret `^`.
+[^3]: The footnote link is numbered based on the order of the labels.
+[^custom label]: Footnote labels can contain any text within square brackets.
+```
+
+**Output:**
+
+This footnote[^1] links to the bottom[^custom label] of the page[^3].
+
+[^1]: Footnote labels start with a caret `^`.
+[^3]: The footnote link is numbered based on the order of the labels.
+[^custom label]: Footnote labels can contain any text within square brackets.
+
+---
+
 ### Tables
 
+**Markdown:**
+```nohighlight
+| This is header | This is another header |
+| -------------- | ---------------------- |
+| An item        | Another item           |
+```
+
+**Output:**
+
 | This is header | This is another header |
 | -------------- | ---------------------- |
 | An item        | Another item           |
-| Big item       | Small item             |
 
+---
 
 ### Codeblock Syntax Highlighting
 Syntax highlighting is provided by `highlight.js`.
 To activate syntax highlighting, put the language directly after the starting backticks.
 
+**Markdown:**
+````nohighlight
+```python
+import os
+
+path = os.path.join("foo", "bar")
+```
+````
+
+**Output:**
 ```python
 import os
 
diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py
index 0faf722c..11d2b792 100644
--- a/pydis_site/apps/content/utils.py
+++ b/pydis_site/apps/content/utils.py
@@ -1,9 +1,11 @@
 from pathlib import Path
-from typing import Dict, Union
+from typing import Dict, Tuple
 
+import frontmatter
+import markdown
 import yaml
 from django.http import Http404
-from markdown2 import markdown
+from markdown.extensions.toc import TocExtension
 
 
 def get_category(path: Path) -> Dict[str, str]:
@@ -31,29 +33,25 @@ def get_category_pages(path: Path) -> Dict[str, Dict]:
 
     for item in path.glob("*.md"):
         if item.is_file():
-            md = markdown(item.read_text(), extras=["metadata"])
-            pages[item.stem] = md.metadata
+            pages[item.stem] = frontmatter.load(item)
 
     return pages
 
 
-def get_page(path: Path) -> Dict[str, Union[str, Dict]]:
+def get_page(path: Path) -> Tuple[str, Dict]:
     """Get one specific page."""
     if not path.is_file():
         raise Http404("Page not found.")
 
-    html = markdown(
-        path.read_text(encoding="utf-8"),
-        extras=[
-            "metadata",
-            "fenced-code-blocks",
-            "highlightjs-lang",
-            "header-ids",
-            "strike",
-            "target-blank-links",
-            "tables",
-            "task_list"
+    metadata, content = frontmatter.parse(path.read_text(encoding="utf-8"))
+    html = markdown.markdown(
+        content,
+        extensions=[
+            "extra",
+            # Empty string for marker to disable text searching for [TOC]
+            # By using a metadata key instead, we save time on long markdown documents
+            TocExtension(title="Table of Contents:", permalink=True, marker="")
         ]
     )
 
-    return {"content": str(html), "metadata": html.metadata}
+    return str(html), metadata
diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py
index 91aed7f0..4a2ed2d6 100644
--- a/pydis_site/apps/content/views/page_category.py
+++ b/pydis_site/apps/content/views/page_category.py
@@ -35,18 +35,19 @@ class PageOrCategoryView(TemplateView):
 
         if self.full_location.is_dir():
             context["categories"] = utils.get_categories(self.full_location)
+            context["pages"] = utils.get_category_pages(self.full_location)
+
             category = utils.get_category(self.full_location)
-            context["category_info"] = category
             context["page_title"] = category["name"]
             context["page_description"] = category["description"]
-            context["pages"] = utils.get_category_pages(self.full_location)
+
             context["path"] = f"{self.location}/"  # Add trailing slash here to simplify template
         elif self.full_location.with_suffix(".md").is_file():
-            page_result = utils.get_page(self.full_location.with_suffix(".md"))
-            context["page"] = page_result
-            context["page_title"] = page_result["metadata"]["title"]
-            context["page_description"] = page_result["metadata"]["description"]
-            context["relevant_links"] = page_result["metadata"].get("relevant_links", {})
+            page, metadata = utils.get_page(self.full_location.with_suffix(".md"))
+            context["page"] = page
+            context["page_title"] = metadata["title"]
+            context["page_description"] = metadata["description"]
+            context["relevant_links"] = metadata.get("relevant_links", {})
         else:
             raise Http404
 
diff --git a/pydis_site/static/css/content/page.css b/pydis_site/static/css/content/page.css
index f46d6b15..57d7472b 100644
--- a/pydis_site/static/css/content/page.css
+++ b/pydis_site/static/css/content/page.css
@@ -6,11 +6,26 @@ i.has-icon-padding {
     padding: 0 10px 25px 0;
 }
 
-pre {
-    /*
-     * Style it the same as the <code> tag, since highlight.js does not style
-     * backgrounds of <pre> tags but bulma does, resulting in a weird off-white
-     * border.
-     */
-    background-color: #282c34;
+/*
+ * Move padding padding from <pre> tag to hljs <code> tags so the padding
+ * space is colored the same as the background of hljs <code> blocks.
+ */
+.content pre {
+    padding: 0;
+}
+
+code.hljs {
+    padding: 1.75em 2em;
+}
+
+/*
+ * Show header permalink on hover.
+ */
+.headerlink {
+    display: none;
+    padding-left: 0.5em;
+}
+
+:is(h1, h2, h3, h4, h5, h6):hover > .headerlink {
+    display: inline;
 }
diff --git a/pydis_site/templates/content/base.html b/pydis_site/templates/content/base.html
index 1508dfb3..19eec5d4 100644
--- a/pydis_site/templates/content/base.html
+++ b/pydis_site/templates/content/base.html
@@ -3,7 +3,7 @@
 
 {% block title %}{{ page_title }}{% endblock %}
 {% block head %}
-<meta property="og:title" content="Python Discord - {{ page_title }}" />
+    <meta property="og:title" content="Python Discord - {{ page_title }}" />
     <meta property="og:type" content="website" />
     <meta property="og:description" content="{{ page_description }}" />
     <link rel="stylesheet" href="{% static "css/content/page.css" %}">
diff --git a/pydis_site/templates/content/page.html b/pydis_site/templates/content/page.html
index 5e820c26..06d74208 100644
--- a/pydis_site/templates/content/page.html
+++ b/pydis_site/templates/content/page.html
@@ -12,7 +12,7 @@
     {% if relevant_links|length > 0 %}
         <div class="columns is-variable is-8">
             <div class="column is-two-thirds">
-                {{ page.content|safe }}
+                {{ page|safe }}
             </div>
             <div class="column">
                 <div class="box">
@@ -26,6 +26,6 @@
             </div>
         </div>
     {% else %}
-        <div>{{ page.content|safe }}</div>
+        <div>{{ page|safe }}</div>
     {% endif %}
 {% endblock %}