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.

2 files changed, 58 insertions, 19 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 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"),
+        }