diff options
author | 2021-03-29 17:51:10 +0800 | |
---|---|---|
committer | 2021-03-29 17:51:10 +0800 | |
commit | 69f33290b8bd12b95bb6c620a9a1422a5d11b798 (patch) | |
tree | d94133a648ec0b1d92798155bdc7dd50a358d2fe | |
parent | Document additional markdown features. (diff) |
Allow adding a table of contents to a page.
-rw-r--r-- | pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md | 2 | ||||
-rw-r--r-- | pydis_site/apps/content/utils.py | 12 | ||||
-rw-r--r-- | pydis_site/apps/content/views/page_category.py | 1 | ||||
-rw-r--r-- | pydis_site/static/css/content/page.css | 19 | ||||
-rw-r--r-- | pydis_site/templates/content/page.html | 28 |
5 files changed, 50 insertions, 12 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 67666428..c2d9d975 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 @@ -5,6 +5,7 @@ icon: fas fa-info relevant_links: Contributing to Site: https://pythondiscord.com/pages/contributing/site/ Using Git: https://pythondiscord.com/pages/contributing/working-with-git/ +toc: 4 --- Pages, which include guides, articles, and other static content, are stored in markdown files in the `site` repository on Github. @@ -80,6 +81,7 @@ Pages, which include guides, articles, and other static content,... ### Optional Fields - **icon:** Icon for the category entry for the page. Default: `fab fa-python` <i class="fab fa-python is-black" aria-hidden="true"></i> - **relevant_links:** A YAML dictionary containing `text:link` pairs. See the example above. +- **toc:** A number representing the smallest heading tag to show in the table of contents. ## Extended Markdown diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index 726c991f..d6886ce2 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -44,14 +44,20 @@ def get_page(path: Path) -> Tuple[str, Dict]: raise Http404("Page not found.") metadata, content = frontmatter.parse(path.read_text(encoding="utf-8")) - html = markdown.markdown( - content, + toc_depth = metadata.get("toc", 1) + + md = markdown.Markdown( 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="") + TocExtension(permalink=True, marker="", toc_depth=toc_depth) ] ) + html = md.convert(content) + + # Don't set the TOC if the metadata does not specify one + if "toc" in metadata: + metadata["toc"] = md.toc 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 711d6a56..a995d2a1 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -67,6 +67,7 @@ class PageOrCategoryView(TemplateView): "page_title": metadata["title"], "page_description": metadata["description"], "relevant_links": metadata.get("relevant_links", {}), + "toc": metadata.get("toc") } @staticmethod diff --git a/pydis_site/static/css/content/page.css b/pydis_site/static/css/content/page.css index 97b297b2..3ac41d1b 100644 --- a/pydis_site/static/css/content/page.css +++ b/pydis_site/static/css/content/page.css @@ -49,3 +49,22 @@ img + em { /* Style */ font-size: .875em; } + +/* + * Remove extra padding on the left of TOC items + */ +ul.menu-list.toc { + margin-left: 0; +} + +/* + * Remove bullets set by the markdown extension, since bulma adds vertical + * lines to represent nesting + */ +.toc li { + list-style-type: none; +} +/* ..but we still want bullets on the top <ul> items */ +.toc > ul > li { + list-style-type: disc; +} diff --git a/pydis_site/templates/content/page.html b/pydis_site/templates/content/page.html index 06d74208..45aa8221 100644 --- a/pydis_site/templates/content/page.html +++ b/pydis_site/templates/content/page.html @@ -9,20 +9,30 @@ {% endblock %} {% block page_content %} - {% if relevant_links|length > 0 %} + {% if relevant_links or toc %} <div class="columns is-variable is-8"> <div class="column is-two-thirds"> {{ page|safe }} </div> <div class="column"> - <div class="box"> - <p class="menu-label">Relevant links</p> - <ul class="menu-list"> - {% for value, link in relevant_links.items %} - <li><a class="has-text-link" href="{{link}}">{{ value }}</a></li> - {% endfor %} - </ul> - </div> + {% if toc %} + <div class="box"> + <p class="menu-label">Table of Contents</p> + <ul class="menu-list toc"> + {{ toc|safe }} + </ul> + </div> + {% endif %} + {% if relevant_links %} + <div class="box"> + <p class="menu-label">Relevant links</p> + <ul class="menu-list"> + {% for value, link in relevant_links.items %} + <li><a class="has-text-link" href="{{link}}">{{ value }}</a></li> + {% endfor %} + </ul> + </div> + {% endif %} </div> </div> {% else %} |