diff options
Diffstat (limited to 'pydis_site')
| -rw-r--r-- | pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md | 59 | ||||
| -rw-r--r-- | pydis_site/apps/content/utils.py | 32 | ||||
| -rw-r--r-- | pydis_site/apps/content/views/page_category.py | 15 | ||||
| -rw-r--r-- | pydis_site/static/css/content/page.css | 29 | ||||
| -rw-r--r-- | pydis_site/templates/content/base.html | 2 | ||||
| -rw-r--r-- | pydis_site/templates/content/page.html | 4 |
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 %} |