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 +++++------- 4 files changed, 8 insertions(+), 10 deletions(-) (limited to 'pydis_site/apps/content/resources') 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 -- 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/apps/content/resources') 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/apps/content/resources') 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/apps/content/resources') 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
    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 %}
    {{ page|safe }}
    -
    -

    Relevant links

    -
      - {% for value, link in relevant_links.items %} -
    • {{ value }}
      • - {% endfor %} -
    -
    + {% if toc %} +
    +

    Table of Contents

    +
      + {{ toc|safe }} +
    +
    + {% endif %} + {% if relevant_links %} +
    +

    Relevant links

    +
      + {% for value, link in relevant_links.items %} +
    • {{ value }}
      • + {% endfor %} +
    +
    + {% endif %}
    {% else %} -- cgit v1.2.3 From 4208626262d6cf790da1c0e00765b375fa427aa7 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Thu, 1 Apr 2021 16:29:29 +0800 Subject: Place category pages in the same directory as categories. --- .../resources/guides/pydis-guides/how-to-contribute-a-page.md | 6 +++--- pydis_site/apps/content/tests/helpers.py | 4 ++-- pydis_site/apps/content/tests/test_views.py | 1 - pydis_site/apps/content/utils.py | 3 ++- pydis_site/apps/content/views/page_category.py | 11 ++++------- 5 files changed, 11 insertions(+), 14 deletions(-) (limited to 'pydis_site/apps/content/resources') 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 c2d9d975..51f1097d 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 @@ -36,14 +36,14 @@ 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**. +#### Having the Category Also Be a Page +In order to make categories a page, just create a page **with the same name as the category folder** in the category's parent directory. ```plaintext guides +├── contributing.md ├── contributing │   ├── _info.yml -│   ├── contributing.md │   └── bot.md └── _info.yml ``` diff --git a/pydis_site/apps/content/tests/helpers.py b/pydis_site/apps/content/tests/helpers.py index 59cd3bd6..202dee42 100644 --- a/pydis_site/apps/content/tests/helpers.py +++ b/pydis_site/apps/content/tests/helpers.py @@ -50,9 +50,9 @@ class MockPagesTestCase(TestCase): ├── root.md ├── root_without_metadata.md ├── not_a_page.md + ├── tmp.md ├── tmp |   ├── _info.yml - |   ├── tmp.md |   └── category |    ├── _info.yml |      └── subcategory_without_info @@ -86,6 +86,6 @@ class MockPagesTestCase(TestCase): # for testing purposes. # See: https://jmcgeheeiv.github.io/pyfakefs/release/usage.html#os-temporary-directories self.fs.create_file("tmp/_info.yml", contents=CATEGORY_INFO) - self.fs.create_file("tmp/tmp.md", contents=MARKDOWN_WITH_METADATA) + self.fs.create_file("tmp.md", contents=MARKDOWN_WITH_METADATA) self.fs.create_file("tmp/category/_info.yml", contents=MARKDOWN_WITH_METADATA) self.fs.create_dir("tmp/category/subcategory_without_info") diff --git a/pydis_site/apps/content/tests/test_views.py b/pydis_site/apps/content/tests/test_views.py index 81c4012b..ab266b29 100644 --- a/pydis_site/apps/content/tests/test_views.py +++ b/pydis_site/apps/content/tests/test_views.py @@ -29,7 +29,6 @@ def patch_dispatch_attributes(view: PageOrCategoryView, location: str) -> None: view.full_location = view.location # Possible places to find page content information - view.category_page_path = view.full_location.joinpath(view.location.stem).with_suffix(".md") view.category_path = view.full_location view.page_path = view.full_location.with_suffix(".md") diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index d6886ce2..d3f270ff 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -32,7 +32,8 @@ def get_category_pages(path: Path) -> Dict[str, Dict]: pages = {} for item in path.glob("*.md"): - if item.is_file(): + # Only list page if there is no category with the same name + if item.is_file() and not item.with_suffix("").is_dir(): pages[item.stem] = frontmatter.load(item).metadata return pages diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index a995d2a1..8783e33f 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -19,7 +19,6 @@ class PageOrCategoryView(TemplateView): 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") @@ -27,7 +26,7 @@ class PageOrCategoryView(TemplateView): def get_template_names(self) -> t.List[str]: """Checks if the view uses the page template or listing template.""" - if self.category_page_path.is_file() or self.page_path.is_file(): + if self.page_path.is_file(): template_name = "content/page.html" elif self.category_path.is_dir(): template_name = "content/listing.html" @@ -40,13 +39,11 @@ class PageOrCategoryView(TemplateView): """Assign proper context variables based on what resource user requests.""" context = super().get_context_data(**kwargs) - if self.category_page_path.is_file(): - context.update(self._get_page_context(self.category_page_path)) + if self.page_path.is_file(): + context.update(self._get_page_context(self.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 @@ -71,7 +68,7 @@ class PageOrCategoryView(TemplateView): } @staticmethod - def _get_category_context(path) -> t.Dict[str, t.Any]: + def _get_category_context(path: Path) -> t.Dict[str, t.Any]: category = utils.get_category(path) return { "categories": utils.get_categories(path), -- cgit v1.2.3 From ffad966760d99d5ed18c6187415712635d9b1cc4 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Thu, 1 Apr 2021 16:48:50 +0800 Subject: Document defining a table of contents for a page. --- .../pydis-guides/how-to-contribute-a-page.md | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'pydis_site/apps/content/resources') 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 51f1097d..0bf5aa27 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 @@ -82,6 +82,7 @@ Pages, which include guides, articles, and other static content,... - **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. + See: [Table of Contents](#table-of-contents) ## Extended Markdown @@ -187,3 +188,29 @@ To add an image caption, place a sentence with italics *right below* the image l *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. + +--- + +### Table of Contents +In order to show the table of contents on a page, simply define the `toc` key in the page metadata. + +The value of the `toc` key corresponds to the smallest heading to list in the table of contents. +For example, with markdown content like this: + +```markdown +# Header 1 +words +### Header 3 +more words +# Another Header 1 +## Header 2 +even more words +``` + +and `toc: 2` in the page metadata, only `Header 1`, `Another Header 1` and `Header 2` will be listed in the table of contents. + +To use a custom label in the table of contents for a heading, set the `data-toc-label` attribute in the heading line. See [HTML Attributes](#html-attributes) for more information. + +```markdown +# Header 1 {: data-toc-label="Header One" } +``` -- cgit v1.2.3 From d90cac6a70125f1d7486b6a8f04e1d7c3642b542 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Thu, 1 Apr 2021 20:15:40 +0800 Subject: Update misleading documentation. --- .../content/resources/guides/pydis-guides/how-to-contribute-a-page.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'pydis_site/apps/content/resources') 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 0bf5aa27..726cb7b2 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 @@ -50,7 +50,8 @@ guides 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*. +However, `www.pythondiscord.com/guides/contributing` will render `contributing.md` rather than show the category contents. +A dropdown menu will be automatically generated in the top right corner of the page listing the children of the category page. Therefore, `www.pythondiscord.com/guides/contributing/bot` will then render `bot.md`, with backlinks to `contributing.md`. -- cgit v1.2.3