From 624e87d15ccfbe4ba2410dcaab0b4fb494b664e5 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Sat, 27 Mar 2021 12:42:07 +0800 Subject: Improve content page and listing metadata keys. Make category `title` consistent with page `title`. Simplify `icon` key, since there is no benefit to defining the icon class and the icon separately. Allow overriding the `icon` for category entries just like page entries. --- pydis_site/apps/content/resources/_info.yml | 2 +- pydis_site/apps/content/resources/guides/_info.yml | 2 +- .../apps/content/resources/guides/pydis-guides/_info.yml | 2 +- .../guides/pydis-guides/how-to-contribute-a-page.md | 12 +++++------- pydis_site/apps/content/views/page_category.py | 5 +++-- pydis_site/templates/content/listing.html | 6 +++--- 6 files changed, 14 insertions(+), 15 deletions(-) (limited to 'pydis_site') diff --git a/pydis_site/apps/content/resources/_info.yml b/pydis_site/apps/content/resources/_info.yml index 583cab18..6553dcc6 100644 --- a/pydis_site/apps/content/resources/_info.yml +++ b/pydis_site/apps/content/resources/_info.yml @@ -1,2 +1,2 @@ -name: Pages +title: Pages description: Guides, articles, and pages hosted on the site. diff --git a/pydis_site/apps/content/resources/guides/_info.yml b/pydis_site/apps/content/resources/guides/_info.yml index 59c60a7b..2f65eaf9 100644 --- a/pydis_site/apps/content/resources/guides/_info.yml +++ b/pydis_site/apps/content/resources/guides/_info.yml @@ -1,2 +1,2 @@ -name: Guides +title: Guides description: Made by us, for you. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml index 7c9a2225..c126a68a 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml +++ b/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml @@ -1,2 +1,2 @@ -name: Python Discord Guides +title: Python Discord Guides description: Guides related to the Python Discord server and community. 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 f258ef74..51486bfe 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 @@ -1,8 +1,7 @@ --- title: How to Contribute a Page description: Learn how to write and publish a page to this website. -icon_class: fas -icon: fa-info +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/ @@ -27,8 +26,9 @@ For example, the file `pydis_site/apps/content/resources/hello-world.md` will re Nested folders represent page categories on the website. Each folder under the root folder must include a `_info.yml` file with the following: ```yml -name: Category name +title: Category name description: Category description +icon: fas fa-folder # Optional ``` All the markdown files in this folder will then be under this category. @@ -44,8 +44,7 @@ The metadata is written in YAML, and should be enclosed in triple dashes `---` * --- title: How to Contribute a Page description: Learn how to write and publish a page to this website. -icon_class: fas -icon: fa-info +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/ @@ -59,8 +58,7 @@ Pages, which include guides, articles, and other static content,... - **description:** Short, 1-2 line description of the page's content. ### Optional Fields -- **icon_class:** Favicon class for the category entry for the page. Default: `fab` -- **icon:** Favicon for the category entry for the page. Default: `fa-python` +- **icon:** Icon for the category entry for the page. Default: `fab fa-python` - **relevant_links:** A YAML dictionary containing `text:link` pairs. See the example above. ## Extended Markdown diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index eec4e7e5..723c5ad0 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -38,8 +38,9 @@ class PageOrCategoryView(TemplateView): context["pages"] = utils.get_category_pages(self.full_location) category = utils.get_category(self.full_location) - context["page_title"] = category["name"] + context["page_title"] = category["title"] context["page_description"] = category["description"] + context["icon"] = category.get("icon") context["path"] = f"{self.location}/" # Add trailing slash here to simplify template elif self.full_location.with_suffix(".md").is_file(): @@ -53,7 +54,7 @@ class PageOrCategoryView(TemplateView): context["breadcrumb_items"] = [ { - "name": utils.get_category(settings.PAGES_PATH / location)["name"], + "name": utils.get_category(settings.PAGES_PATH / location)["title"], "path": str(location) } for location in reversed(self.location.parents) ] diff --git a/pydis_site/templates/content/listing.html b/pydis_site/templates/content/listing.html index 6de306b0..ef0ef919 100644 --- a/pydis_site/templates/content/listing.html +++ b/pydis_site/templates/content/listing.html @@ -4,11 +4,11 @@ {% for category, data in categories.items %}
- + - {{ data.name }} + {{ data.title }}

{{ data.description }}

@@ -16,7 +16,7 @@ {% for page, data in pages.items %}
- + {{ data.title }} -- cgit v1.2.3 From 3d75841b2e7a8ca219d77314c1533827e8213b8e Mon Sep 17 00:00:00 2001 From: kosayoda Date: Mon, 29 Mar 2021 15:23:36 +0800 Subject: Allow displaying a page at a category path. This is useful for our /contributing pages, which have a main contributing page at /contributing but project pages under the same path, /contributing/bot etc. --- .../pydis-guides/how-to-contribute-a-page.md | 20 ++++++++ pydis_site/apps/content/views/page_category.py | 57 ++++++++++++++-------- 2 files changed, 58 insertions(+), 19 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 51486bfe..303a2c0f 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 @@ -21,8 +21,10 @@ As website changes require staff approval, discussing the page content beforehan ## Creating the Page All pages are located in the `site` repo, at the path `pydis_site/apps/content/resources/`. This is the root folder, which corresponds to the URL `www.pythondiscord.com/pages/`. + For example, the file `pydis_site/apps/content/resources/hello-world.md` will result in a page available at `www.pythondiscord.com/pages/hello-world`. +#### Page Categories Nested folders represent page categories on the website. Each folder under the root folder must include a `_info.yml` file with the following: ```yml @@ -33,6 +35,24 @@ icon: fas fa-folder # Optional All the markdown files in this folder will then be under this category. +#### Having the Category also be a Page +In order to make categories a page, place a page inside the category folder **with the same name as the category folder**. + +```plaintext +guides +├── contributing +│   ├── _info.yml +│   ├── contributing.md +│   └── bot.md +└── _info.yml +``` + +In the above example, `www.pythondiscord.com/guides/` will list `Contributing` as a category entry with information from `contributing/_info.yml`. + +However, `www.pythondiscord.com/guides/contributing` will render `contributing.md` rather than show the category contents, so *it is the article's responsibility to link to any subpages under the article*. + +Therefore, `www.pythondiscord.com/guides/contributing/bot` will then render `bot.md`, with backlinks to `contributing.md`. + ## Writing the Page Files representing pages are in `.md` (Markdown) format, with all-lowercase filenames and spaces replaced with `-` characters. diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index 723c5ad0..711d6a56 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -14,16 +14,23 @@ class PageOrCategoryView(TemplateView): def dispatch(self, request: t.Any, *args, **kwargs) -> t.Any: """Conform URL path location to the filesystem path.""" self.location = Path(kwargs.get("location", "")) + + # URL location on the filesystem self.full_location = settings.PAGES_PATH / self.location + # Possible places to find page content information + self.category_page_path = self.full_location.joinpath(self.location.stem).with_suffix(".md") + self.category_path = self.full_location + self.page_path = self.full_location.with_suffix(".md") + return super().dispatch(request, *args, **kwargs) def get_template_names(self) -> t.List[str]: """Checks if the view uses the page template or listing template.""" - if self.full_location.is_dir(): - template_name = "content/listing.html" - elif self.full_location.with_suffix(".md").is_file(): + if self.category_page_path.is_file() or self.page_path.is_file(): template_name = "content/page.html" + elif self.category_path.is_dir(): + template_name = "content/listing.html" else: raise Http404 @@ -33,22 +40,13 @@ class PageOrCategoryView(TemplateView): """Assign proper context variables based on what resource user requests.""" context = super().get_context_data(**kwargs) - 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["page_title"] = category["title"] - context["page_description"] = category["description"] - context["icon"] = category.get("icon") - - context["path"] = f"{self.location}/" # Add trailing slash here to simplify template - elif self.full_location.with_suffix(".md").is_file(): - 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", {}) + if self.category_page_path.is_file(): + context.update(self._get_page_context(self.category_page_path)) + elif self.category_path.is_dir(): + context.update(self._get_category_context(self.category_path)) + context["path"] = f"{self.location}/" # Add trailing slash to simplify template + elif self.page_path.is_file(): + context.update(self._get_page_context(self.page_path)) else: raise Http404 @@ -60,3 +58,24 @@ class PageOrCategoryView(TemplateView): ] return context + + @staticmethod + def _get_page_context(path: Path) -> t.Dict[str, t.Any]: + page, metadata = utils.get_page(path) + return { + "page": page, + "page_title": metadata["title"], + "page_description": metadata["description"], + "relevant_links": metadata.get("relevant_links", {}), + } + + @staticmethod + def _get_category_context(path) -> t.Dict[str, t.Any]: + category = utils.get_category(path) + return { + "categories": utils.get_categories(path), + "pages": utils.get_category_pages(path), + "page_title": category["title"], + "page_description": category["description"], + "icon": category.get("icon"), + } -- cgit v1.2.3 From 8b68a5a4ce7ff33d76d10a980087048a73764b29 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Mon, 29 Mar 2021 15:25:53 +0800 Subject: Document additional markdown features. Adds image caption capabilities and documents missing HTML extensions available. --- .../pydis-guides/how-to-contribute-a-page.md | 26 ++++++++++++++++++++++ pydis_site/static/css/content/page.css | 20 +++++++++++++++++ 2 files changed, 46 insertions(+) (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 303a2c0f..67666428 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 @@ -159,3 +159,29 @@ import os path = os.path.join("foo", "bar") ``` + +--- + +### HTML Attributes +To add HTML attributes to certain lines/paragraphs, [see this page](https://python-markdown.github.io/extensions/attr_list/#the-list) for the format and where to put it. + +This can be useful for setting the image size when adding an image using markdown (see the [Image Captions](#image-captions) section for an example), or for adding bulma styles to certain elements (like the warning notification [here](/pages/guides/pydis-guides/contributing/sir-lancebot#setup-instructions)). +**This should be used sparingly, as it reduces readability and simplicity of the article.** + +--- + +### Image Captions +To add an image caption, place a sentence with italics *right below* the image link + +**Markdown:** +```nohighlight +![Summer Code Jam 2020](/static/images/events/summer_code_jam_2020.png){: width="400" } +*Summmer Code Jam 2020 banner with event information.* +``` + +**Output:** + +![Summer Code Jam 2020](/static/images/events/summer_code_jam_2020.png){: width="400"} +*Summer Code Jam 2020 banner with event information.* + +> Note: To display a regular italicized line below an image, leave an empty line between the two. diff --git a/pydis_site/static/css/content/page.css b/pydis_site/static/css/content/page.css index 57d7472b..97b297b2 100644 --- a/pydis_site/static/css/content/page.css +++ b/pydis_site/static/css/content/page.css @@ -29,3 +29,23 @@ code.hljs { :is(h1, h2, h3, h4, h5, h6):hover > .headerlink { display: inline; } + +/* + * Display tags immediately following tags like figure subcaptions. + * Note: There must not be a newline between the image and the italicized line + * for this to work. Otherwise, it's regular markdown. + * + * Image caption: + * + * ![Title](Source) + * *This is my caption.* + * + */ +img + em { + /* Place the caption on it's own line */ + display: block; + white-space: pre; + + /* Style */ + font-size: .875em; +} -- cgit v1.2.3 From 69f33290b8bd12b95bb6c620a9a1422a5d11b798 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Mon, 29 Mar 2021 17:51:10 +0800 Subject: Allow adding a table of contents to a page. --- .../pydis-guides/how-to-contribute-a-page.md | 2 ++ pydis_site/apps/content/utils.py | 12 +++++++--- pydis_site/apps/content/views/page_category.py | 1 + pydis_site/static/css/content/page.css | 19 +++++++++++++++ pydis_site/templates/content/page.html | 28 +++++++++++++++------- 5 files changed, 50 insertions(+), 12 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 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` - **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