From 6ccec0d866c44cd7f9789a396ef6ec6cd2cd5df8 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Wed, 24 Mar 2021 19:55:16 +0800 Subject: 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. --- .../pydis-guides/how-to-contribute-a-page.md | 59 +++++++++++++++++++++- pydis_site/apps/content/utils.py | 32 ++++++------ pydis_site/apps/content/views/page_category.py | 15 +++--- pydis_site/static/css/content/page.css | 29 ++++++++--- pydis_site/templates/content/base.html | 2 +- pydis_site/templates/content/page.html | 4 +- 6 files changed, 106 insertions(+), 35 deletions(-) (limited to 'pydis_site') 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 `` 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 HTML +generated from YAML 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 tag, since highlight.js does not style - * backgrounds of 
 tags but bulma does, resulting in a weird off-white
-     * border.
-     */
-    background-color: #282c34;
+/*
+ * Move padding padding from 
 tag to hljs  tags so the padding
+ * space is colored the same as the background of hljs  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 %}
-
+    
     
     
     
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 %}
         

             

-                {{ page.content|safe }}
+                {{ page|safe }}
             

             

                 

@@ -26,6 +26,6 @@
             

         

     {% else %}
-        
{{ page.content|safe }}

+        
{{ page|safe }}

     {% endif %}
 {% endblock %}
-- 
cgit v1.2.3