diff options
Diffstat (limited to 'pydis_site')
| -rw-r--r-- | pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md | 20 | ||||
| -rw-r--r-- | pydis_site/apps/content/views/page_category.py | 57 |
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"), + } |