From aff3a89c3cec04eda096e8f27115e36108ee6286 Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Sun, 4 Oct 2020 18:55:33 +0300 Subject: Change guides system to content system As this system will be used for more than just guides, I had to do some refactoring to match this system with plans. Basically now there isn't guides, but articles instead. --- .../content/resources/content/guides/_info.yml | 2 + .../content/guides/how-to-write-a-guide.md | 63 ++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 pydis_site/apps/content/resources/content/guides/_info.yml create mode 100644 pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/content/guides/_info.yml b/pydis_site/apps/content/resources/content/guides/_info.yml new file mode 100644 index 00000000..8a38271d --- /dev/null +++ b/pydis_site/apps/content/resources/content/guides/_info.yml @@ -0,0 +1,2 @@ +name: Guides +description: Python and PyDis guides. \ No newline at end of file diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md new file mode 100644 index 00000000..072c2538 --- /dev/null +++ b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md @@ -0,0 +1,63 @@ +Title: How to Write a Guide +ShortDescription: Learn how to write a guide for this website +Contributors: ks129 + +When you are interested about how to write guide for this site (like this), then you can learn about it here. +PyDis use Markdown files for guides, but these files have some small differences from standard Markdown (like defining HTML IDs and classes). + +## [Getting Started](#getting-started){: id="getting-started" } +First, you have to have a good idea, that match with PyDis theme. We can't accept guides like *How to bake a cake*, +*How to lose weigth*. These doesn't match with PyDis theme and will be declined. Most of guides theme should be server and Python, but there can be some exceptions, when they are connected with PyDis. +Best way to find out is your idea good is to discuss about it in #dev-core channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. +It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long guide, but then this don't get approved. + +To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). +You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. + +## [Creating a File](#creating-a-file){: id="creating-a-file" } +All guides is located at `site` repository, in `pydis_site/apps/guides/resources/guides`. Under this is root level guides (.md files) and categories (directories). Learn more about categories in [categories section](#categories). + +At this point, you will need your guide name for filename. Replace all your guide name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of guide in URL. + +## [Markdown Metadata](#markdown-metadata){: id="markdown-metadata" } +Guide files have some required metadata, like title, contributors, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: + +```md +Title: My Guide +ShortDescription: This is my short description. +Contributors: person1 + person2 + person3 +RelevantLinks: url1 + url2 + url3 +RelevantLinkValues: Text for url1 + Text for url2 + Text for url3 + +Here comes content of guide... +``` + +You can read more about Markdown metadata [here](https://python-markdown.github.io/extensions/meta_data/). + +### Fields +- **Name:** Easily-readable name for your guide. +- **Short Description:** Small, 1-2 line description that describe what your guide explain. +- **Contributors:** All who have contributed to this guide. One person per-line, and they **have to be at same level**. When you edit guide, add your name to there. +- **Relevant Links and Values:** Links that will be shown at right side. Both key's values have to be at same level, just like for contributors field. + +## [Content](#content){: id="content" } +For content, mostly you can use standard markdown, but there is a few addition that is available. + +### HTML classes and IDs +To provide HTML classes and/or IDs, this use `{: id="myid" class="class1 class2" }`. When using it at header, place this **right after** title, no space between them. For mutliline items, place them next line after end of block. You can read more about it [here](https://python-markdown.github.io/extensions/attr_list/). + +## [Categories](#categories){: id="categories" } +To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/guides/resources/guides` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: + +```yml +name: Category name +description: Category description +``` + +Then all Markdown files in this folder will be under this category. -- cgit v1.2.3 From 6517bb9078db8b9bb9ca7bbc11c6838309355dcb Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Mon, 5 Oct 2020 16:41:22 +0300 Subject: Migrate content system from Python-Markdown to markdown2 --- Pipfile | 2 +- Pipfile.lock | 85 ++++++++++++---------- .../content/resources/content/guides/_info.yml | 2 +- .../content/guides/how-to-write-a-guide.md | 17 +++-- .../content/tests/test_content/category/test3.md | 7 +- pydis_site/apps/content/tests/test_content/test.md | 15 ++-- .../apps/content/tests/test_content/test2.md | 9 ++- pydis_site/apps/content/tests/test_utils.py | 45 ++++++++---- pydis_site/apps/content/utils.py | 16 ++-- pydis_site/apps/content/views/article.py | 17 +++-- pydis_site/templates/content/article.html | 9 +-- pydis_site/templates/content/articles.html | 4 +- pydis_site/templates/content/category.html | 4 +- 13 files changed, 130 insertions(+), 102 deletions(-) (limited to 'pydis_site/apps/content/resources') diff --git a/Pipfile b/Pipfile index 99c2cb30..a9fcf0ff 100644 --- a/Pipfile +++ b/Pipfile @@ -21,7 +21,7 @@ pyuwsgi = {version = "~=2.0",sys_platform = "!='win32'"} django-allauth = "~=0.41" sentry-sdk = "~=0.14" gitpython = "~=3.1.7" -markdown = "~=3.2.2" +markdown2 = "~=2.3.9" [dev-packages] coverage = "~=5.0" diff --git a/Pipfile.lock b/Pipfile.lock index 87e743c8..c120cc63 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "3cd339ce2e945d1728b52bdc00c615c154797e0fbcda6e75ee78ab069545e3bc" + "sha256": "4f47bb9faf104653e2cb19990b5d8fbcde54d888447da13ff3375b03035d40a1" }, "pipfile-spec": 6, "requires": { @@ -135,11 +135,11 @@ }, "djangorestframework": { "hashes": [ - "sha256:6dd02d5a4bd2516fb93f80360673bf540c3b6641fec8766b1da2870a5aa00b32", - "sha256:8b1ac62c581dbc5799b03e535854b92fc4053ecfe74bad3f9c05782063d4196b" + "sha256:5cc724dc4b076463497837269107e1995b1fbc917468d1b92d188fd1af9ea789", + "sha256:a5967b68a04e0d97d10f4df228e30f5a2d82ba63b9d03e1759f84993b7bf1b53" ], "index": "pypi", - "version": "==3.11.1" + "version": "==3.11.2" }, "djangorestframework-bulk": { "hashes": [ @@ -157,11 +157,11 @@ }, "gitpython": { "hashes": [ - "sha256:080bf8e2cf1a2b907634761c2eaefbe83b69930c94c66ad11b65a8252959f912", - "sha256:1858f4fd089abe92ae465f01d5aaaf55e937eca565fb2c1fce35a51b5f85c910" + "sha256:138016d519bf4dd55b22c682c904ed2fd0235c3612b2f8f65ce218ff358deed8", + "sha256:a03f728b49ce9597a6655793207c6ab0da55519368ff5961e4a74ae475b9fa8e" ], "index": "pypi", - "version": "==3.1.8" + "version": "==3.1.9" }, "idna": { "hashes": [ @@ -193,9 +193,16 @@ "sha256:1fafe3f1ecabfb514a5285fca634a53c1b32a81cb0feb154264d55bf2ff22c17", "sha256:c467cd6233885534bf0fe96e62e3cf46cfc1605112356c4f9981512b8174de59" ], - "index": "pypi", "version": "==3.2.2" }, + "markdown2": { + "hashes": [ + "sha256:89526090907ae5ece66d783c434b35c29ee500c1986309e306ce2346273ada6a", + "sha256:e6b401ec80b75e76a6b3dbb2c8ade513156fa55fa6c30b9640a1abf6184a07c8" + ], + "index": "pypi", + "version": "==2.3.9" + }, "oauthlib": { "hashes": [ "sha256:bee41cc35fcca6e988463cacc3bcb8a96224f470ca547e697b604cc697b2f889", @@ -312,22 +319,22 @@ }, "pyuwsgi": { "hashes": [ - "sha256:1a4dd8d99b8497f109755e09484b0bd2aeaa533f7621e7c7e2a120a72111219d", - "sha256:206937deaebbac5c87692657c3151a5a9d40ecbc9b051b94154205c50a48e963", - "sha256:2cf35d9145208cc7c96464d688caa3de745bfc969e1a1ae23cb046fc10b0ac7e", - "sha256:3ab84a168633eeb55847d59475d86e9078d913d190c2a1aed804c562a10301a3", - "sha256:430406d1bcf288a87f14fde51c66877eaf5e98516838a1c6f761af5d814936fc", - "sha256:72be25ce7aa86c5616c59d12c2961b938e7bde47b7ff6a996ff83b89f7c5cd27", - "sha256:aa4d615de430e2066a1c76d9cc2a70abf2dfc703a82c21aee625b445866f2c3b", - "sha256:aadd231256a672cf4342ef9fb976051949e4d5b616195e696bcb7b8a9c07789e", - "sha256:b15ee6a7759b0465786d856334b8231d882deda5291cf243be6a343a8f3ef910", - "sha256:bd1d0a8d4cb87eb63417a72e6b1bac47053f9b0be550adc6d2a375f4cbaa22f0", - "sha256:d5787779ec24b67ac8898be9dc2b2b4e35f17d79f14361f6cf303d6283a848f2", - "sha256:ecfae85d6504e0ecbba100a795032a88ce8f110b62b93243f2df1bd116eca67f" + "sha256:0bd14517398f494d828d77a9bf72b5a6cbef0112e1cc05e9a0080fa8828ccfa0", + "sha256:285e263a9094389f13cfdefd033a4e99fbed3ad120dba9ac5093846cc03ac5ab", + "sha256:297d1d0b8c472374b12eda7f17a9f5de67cf516612e42b71a7636afb9d1e3974", + "sha256:5439f0f3ef5d6bf1622f341662d04c1d92b88889db40b295419e5fe75a7c7d45", + "sha256:56ecda11e873b2eb937b33d2999766322eebfa82ee5b26a2196a335c4e786186", + "sha256:66a9751f28abf348e0ddccadc4ded47623f2d35cf9609c87b57909d55a4cdc15", + "sha256:890e7e863cb61c8369b6bcfa5d6f323753aaeec2cfaba16741f119c79b964aa7", + "sha256:90e4235020048456ad867aefc383cdf5528b7f6e327555ceec579c428a828759", + "sha256:94d4287b155aa789ce4b6f671c981f7d6c58fc3113330e2f29ac7926cb854645", + "sha256:a425f562f382a097ca49df26b70d47d12f0cf0abf233610f3f58b1f7f780355e", + "sha256:bddeb8df77010d0f842068765a0b3155fdcfd847f14bc1ba89fc7e37914a13d2", + "sha256:dac4a04dc0f69d641dba984e83214d2c2cc098496c5d5585e7d3f4e7a9190f84" ], "index": "pypi", "markers": "sys_platform != 'win32'", - "version": "==2.0.19.1" + "version": "==2.0.19.1.post0" }, "pyyaml": { "hashes": [ @@ -363,11 +370,11 @@ }, "sentry-sdk": { "hashes": [ - "sha256:1a086486ff9da15791f294f6e9915eb3747d161ef64dee2d038a4d0b4a369b24", - "sha256:45486deb031cea6bbb25a540d7adb4dd48cd8a1cc31e6a5ce9fb4f792a572e9a" + "sha256:1d91a0059d2d8bb980bec169578035c2f2d4b93cd8a4fb5b85c81904d33e221a", + "sha256:6222cf623e404c3e62b8e0e81c6db866ac2d12a663b7c1f7963350e3f397522a" ], "index": "pypi", - "version": "==0.17.6" + "version": "==0.18.0" }, "six": { "hashes": [ @@ -513,19 +520,19 @@ }, "flake8": { "hashes": [ - "sha256:15e351d19611c887e482fb960eae4d44845013cc142d42896e9862f775d8cf5c", - "sha256:f04b9fcbac03b0a3e58c0ab3a0ecc462e023a9faf046d57794184028123aa208" + "sha256:749dbbd6bfd0cf1318af27bf97a14e28e5ff548ef8e5b1566ccfb25a11e7c839", + "sha256:aadae8761ec651813c24be05c6f7b4680857ef6afaae4651a4eccaef97ce6c3b" ], "index": "pypi", - "version": "==3.8.3" + "version": "==3.8.4" }, "flake8-annotations": { "hashes": [ - "sha256:09fe1aa3f40cb8fef632a0ab3614050a7584bb884b6134e70cf1fc9eeee642fa", - "sha256:5bda552f074fd6e34276c7761756fa07d824ffac91ce9c0a8555eb2bc5b92d7a" + "sha256:0bcebb0792f1f96d617ded674dca7bf64181870bfe5dace353a1483551f8e5f1", + "sha256:bebd11a850f6987a943ce8cdff4159767e0f5f89b3c88aca64680c2175ee02df" ], "index": "pypi", - "version": "==2.4.0" + "version": "==2.4.1" }, "flake8-bandit": { "hashes": [ @@ -597,18 +604,18 @@ }, "gitpython": { "hashes": [ - "sha256:080bf8e2cf1a2b907634761c2eaefbe83b69930c94c66ad11b65a8252959f912", - "sha256:1858f4fd089abe92ae465f01d5aaaf55e937eca565fb2c1fce35a51b5f85c910" + "sha256:138016d519bf4dd55b22c682c904ed2fd0235c3612b2f8f65ce218ff358deed8", + "sha256:a03f728b49ce9597a6655793207c6ab0da55519368ff5961e4a74ae475b9fa8e" ], "index": "pypi", - "version": "==3.1.8" + "version": "==3.1.9" }, "identify": { "hashes": [ - "sha256:c770074ae1f19e08aadbda1c886bc6d0cb55ffdc503a8c0fe8699af2fc9664ae", - "sha256:d02d004568c5a01261839a05e91705e3e9f5c57a3551648f9b3fb2b9c62c0f62" + "sha256:7c22c384a2c9b32c5cc891d13f923f6b2653aa83e2d75d8f79be240d6c86c4f4", + "sha256:da683bfb7669fa749fc7731f378229e2dbf29a1d1337cbde04106f02236eb29d" ], - "version": "==1.5.3" + "version": "==1.5.5" }, "mccabe": { "hashes": [ @@ -731,10 +738,10 @@ }, "virtualenv": { "hashes": [ - "sha256:43add625c53c596d38f971a465553f6318decc39d98512bc100fa1b1e839c8dc", - "sha256:e0305af10299a7fb0d69393d8f04cb2965dda9351140d11ac8db4e5e3970451b" + "sha256:3d427459dfe5ec3241a6bad046b1d10c0e445940e013c81946458987c7c7e255", + "sha256:9160a8f6196afcb8bb91405b5362651f302ee8e810fc471f5f9ce9a06b070298" ], - "version": "==20.0.31" + "version": "==20.0.32" } } } diff --git a/pydis_site/apps/content/resources/content/guides/_info.yml b/pydis_site/apps/content/resources/content/guides/_info.yml index 8a38271d..369f05d4 100644 --- a/pydis_site/apps/content/resources/content/guides/_info.yml +++ b/pydis_site/apps/content/resources/content/guides/_info.yml @@ -1,2 +1,2 @@ name: Guides -description: Python and PyDis guides. \ No newline at end of file +description: Python and PyDis guides. diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md index 072c2538..8ea438a2 100644 --- a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md +++ b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md @@ -1,11 +1,12 @@ -Title: How to Write a Guide -ShortDescription: Learn how to write a guide for this website -Contributors: ks129 +--- +title: How to Write a Guide +short_description: Learn how to write a guide for this website +--- When you are interested about how to write guide for this site (like this), then you can learn about it here. PyDis use Markdown files for guides, but these files have some small differences from standard Markdown (like defining HTML IDs and classes). -## [Getting Started](#getting-started){: id="getting-started" } +## Getting Started First, you have to have a good idea, that match with PyDis theme. We can't accept guides like *How to bake a cake*, *How to lose weigth*. These doesn't match with PyDis theme and will be declined. Most of guides theme should be server and Python, but there can be some exceptions, when they are connected with PyDis. Best way to find out is your idea good is to discuss about it in #dev-core channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. @@ -14,12 +15,12 @@ It's good idea to wait for staff decision before starting to write guide to avoi To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. -## [Creating a File](#creating-a-file){: id="creating-a-file" } +## Creating a File All guides is located at `site` repository, in `pydis_site/apps/guides/resources/guides`. Under this is root level guides (.md files) and categories (directories). Learn more about categories in [categories section](#categories). At this point, you will need your guide name for filename. Replace all your guide name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of guide in URL. -## [Markdown Metadata](#markdown-metadata){: id="markdown-metadata" } +## Markdown Metadata Guide files have some required metadata, like title, contributors, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: ```md @@ -46,13 +47,13 @@ You can read more about Markdown metadata [here](https://python-markdown.github. - **Contributors:** All who have contributed to this guide. One person per-line, and they **have to be at same level**. When you edit guide, add your name to there. - **Relevant Links and Values:** Links that will be shown at right side. Both key's values have to be at same level, just like for contributors field. -## [Content](#content){: id="content" } +## Content For content, mostly you can use standard markdown, but there is a few addition that is available. ### HTML classes and IDs To provide HTML classes and/or IDs, this use `{: id="myid" class="class1 class2" }`. When using it at header, place this **right after** title, no space between them. For mutliline items, place them next line after end of block. You can read more about it [here](https://python-markdown.github.io/extensions/attr_list/). -## [Categories](#categories){: id="categories" } +## Categories To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/guides/resources/guides` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: ```yml diff --git a/pydis_site/apps/content/tests/test_content/category/test3.md b/pydis_site/apps/content/tests/test_content/category/test3.md index bdde6188..03ddd67b 100644 --- a/pydis_site/apps/content/tests/test_content/category/test3.md +++ b/pydis_site/apps/content/tests/test_content/category/test3.md @@ -1,5 +1,6 @@ -Title: Test 3 -ShortDescription: Testing 3 -Contributors: user3 +--- +title: Test 3 +short_description: Testing 3 +--- This is too test content, but in category. diff --git a/pydis_site/apps/content/tests/test_content/test.md b/pydis_site/apps/content/tests/test_content/test.md index 7a917899..175c1fdb 100644 --- a/pydis_site/apps/content/tests/test_content/test.md +++ b/pydis_site/apps/content/tests/test_content/test.md @@ -1,11 +1,8 @@ -Title: Test -ShortDescription: Testing -Contributors: user -RelevantLinks: https://pythondiscord.com/pages/resources/guides/asking-good-questions/ - https://pythondiscord.com/pages/resources/guides/help-channels/ - https://pythondiscord.com/pages/code-of-conduct/ -RelevantLinkValues: Asking Good Questions - Help Channel Guide - Code of Conduct +--- +title: Test +short_description: Testing +relevant_links: https://pythondiscord.com/pages/resources/guides/asking-good-questions/,https://pythondiscord.com/pages/resources/guides/help-channels/,https://pythondiscord.com/pages/code-of-conduct/ +relevant_link_values: Asking Good Questions,Help Channel Guide,Code of Conduct +--- This is test content. diff --git a/pydis_site/apps/content/tests/test_content/test2.md b/pydis_site/apps/content/tests/test_content/test2.md index f0852356..14d8a54b 100644 --- a/pydis_site/apps/content/tests/test_content/test2.md +++ b/pydis_site/apps/content/tests/test_content/test2.md @@ -1,5 +1,6 @@ -Title: Test 2 -ShortDescription: Testing 2 -Contributors: user2 +--- +title: Test 2 +short_description: Testing 2 +--- -This is too test content. \ No newline at end of file +This is too test content. diff --git a/pydis_site/apps/content/tests/test_utils.py b/pydis_site/apps/content/tests/test_utils.py index 84007b27..bba998fe 100644 --- a/pydis_site/apps/content/tests/test_utils.py +++ b/pydis_site/apps/content/tests/test_utils.py @@ -1,11 +1,10 @@ -import os from pathlib import Path from unittest.mock import patch from django.conf import settings from django.http import Http404 from django.test import TestCase -from markdown import Markdown +from markdown2 import markdown from pydis_site.apps.content import utils @@ -59,22 +58,20 @@ class TestGetArticles(TestCase): for case in ["test", "test2"]: with self.subTest(guide=case): - md = Markdown(extensions=['meta']) - md.convert(BASE_PATH.joinpath(f"{case}.md").read_text()) + md = markdown(BASE_PATH.joinpath(f"{case}.md").read_text(), extras=["metadata"]) self.assertIn(case, result) - self.assertEqual(md.Meta, result[case]) + self.assertEqual(md.metadata, result[case]) def test_get_all_category_articles(self): """Check does this return all category testing content.""" with patch("pydis_site.apps.content.utils._get_base_path", return_value=BASE_PATH): result = utils.get_articles("category") - md = Markdown(extensions=['meta']) - md.convert(BASE_PATH.joinpath("category", "test3.md").read_text()) + md = markdown(BASE_PATH.joinpath("category", "test3.md").read_text(), extras=["metadata"]) self.assertIn("test3", result) - self.assertEqual(md.Meta, result["test3"]) + self.assertEqual(md.metadata, result["test3"]) class TestGetArticle(TestCase): @@ -83,10 +80,20 @@ class TestGetArticle(TestCase): with patch("pydis_site.apps.content.utils._get_base_path", return_value=BASE_PATH): result = utils.get_article("test", None) - md = Markdown(extensions=['meta', 'attr_list', 'fenced_code']) - html = md.convert(BASE_PATH.joinpath("test.md").read_text()) + md = markdown( + BASE_PATH.joinpath("test.md").read_text(), + extras=[ + "metadata", + "fenced-code-blocks", + "header-ids", + "strike", + "target-blank-links", + "tables", + "task_list" + ] + ) - self.assertEqual(result, {"article": html, "metadata": md.Meta}) + self.assertEqual(result, {"article": str(md), "metadata": md.metadata}) def test_get_root_article_dont_exist(self): """Check does this raise Http404 when root article don't exist.""" @@ -99,10 +106,20 @@ class TestGetArticle(TestCase): with patch("pydis_site.apps.content.utils._get_base_path", return_value=BASE_PATH): result = utils.get_article("test3", "category") - md = Markdown(extensions=['meta', 'attr_list', 'fenced_code']) - html = md.convert(BASE_PATH.joinpath("category", "test3.md").read_text()) + md = markdown( + BASE_PATH.joinpath("category", "test3.md").read_text(), + extras=[ + "metadata", + "fenced-code-blocks", + "header-ids", + "strike", + "target-blank-links", + "tables", + "task_list" + ] + ) - self.assertEqual(result, {"article": html, "metadata": md.Meta}) + self.assertEqual(result, {"article": str(md), "metadata": md.metadata}) def test_get_category_article_dont_exist(self): """Check does this raise Http404 when category article don't exist.""" diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index 32c750c3..b2451745 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -5,7 +5,7 @@ from typing import Dict, Optional, Union import yaml from django.conf import settings from django.http import Http404 -from markdown import Markdown +from markdown2 import markdown def _get_base_path() -> Path: @@ -45,10 +45,8 @@ def get_articles(category: Optional[str] = None) -> Dict[str, Dict]: for item in base_dir.iterdir(): if item.is_file() and item.name.endswith(".md"): - md = Markdown(extensions=['meta']) - md.convert(item.read_text()) - - articles[os.path.splitext(item.name)[0]] = md.Meta + md = markdown(item.read_text(), extras=["metadata"]) + articles[os.path.splitext(item.name)[0]] = md.metadata return articles @@ -67,7 +65,9 @@ def get_article(article: str, category: Optional[str]) -> Dict[str, Union[str, D if not article_path.exists() or not article_path.is_file(): raise Http404("Article not found.") - md = Markdown(extensions=['meta', 'attr_list', 'fenced_code']) - html = md.convert(article_path.read_text()) + html = markdown( + article_path.read_text(), + extras=["metadata", "fenced-code-blocks", "header-ids", "strike", "target-blank-links", "tables", "task_list"] + ) - return {"article": html, "metadata": md.Meta} + return {"article": str(html), "metadata": html.metadata} diff --git a/pydis_site/apps/content/views/article.py b/pydis_site/apps/content/views/article.py index 34404719..ede3ba43 100644 --- a/pydis_site/apps/content/views/article.py +++ b/pydis_site/apps/content/views/article.py @@ -34,6 +34,16 @@ class ArticleView(View): else: category_data = {"name": None, "raw_name": None} + relevant_links = { + link: value for link, value in zip( + article_result["metadata"].get("relevant_links", "").split(","), + article_result["metadata"].get("relevant_link_values", "").split(",") + ) + } + + if relevant_links == {"": ""}: + relevant_links = {} + return render( request, "content/article.html", @@ -41,11 +51,6 @@ class ArticleView(View): "article": article_result, "last_modified": datetime.fromtimestamp(os.path.getmtime(path)).strftime("%dth %B %Y"), "category_data": category_data, - "relevant_links": { - link: value for link, value in zip( - article_result["metadata"].get("relevantlinks", []), - article_result["metadata"].get("relevantlinkvalues", []) - ) - } + "relevant_links": relevant_links } ) diff --git a/pydis_site/templates/content/article.html b/pydis_site/templates/content/article.html index de6cd28d..f4282df2 100644 --- a/pydis_site/templates/content/article.html +++ b/pydis_site/templates/content/article.html @@ -1,11 +1,11 @@ {% extends 'base/base.html' %} {% load static %} -{% block title %}{{ metadata.title|first }}{% endblock %} +{% block title %}{{ article.metadata.title }}{% endblock %} {% block head %} - + @@ -23,7 +23,7 @@ {% if category_data.raw_name is not None %}
  • {{ category_data.name }}
    • {% endif %} -
  • {{ article.metadata.title|first }}
    • +
  • {{ article.metadata.title }}
    • @@ -32,13 +32,12 @@
    -

    {{ article.metadata.title|first }}

    +

    {{ article.metadata.title }}

    {{ article.article|safe }}

    Last modified: {{ last_modified }}
    - Contributors: {{ article.metadata.contributors|join:", " }}

    diff --git a/pydis_site/templates/content/articles.html b/pydis_site/templates/content/articles.html index 6fea66e5..363bbb4f 100644 --- a/pydis_site/templates/content/articles.html +++ b/pydis_site/templates/content/articles.html @@ -29,9 +29,9 @@ - {{ data.title.0 }} + {{ data.title }} -

    {{ data.shortdescription.0 }}

    +

    {{ data.short_description }}

    {% endfor %} {% for category, data in categories.items %} diff --git a/pydis_site/templates/content/category.html b/pydis_site/templates/content/category.html index 61e20c43..c2201745 100644 --- a/pydis_site/templates/content/category.html +++ b/pydis_site/templates/content/category.html @@ -33,9 +33,9 @@ - {{ data.title.0 }} + {{ data.title }} -

    {{ data.shortdescription.0 }}

    +

    {{ data.short_description }}

    {% endfor %}
    -- cgit v1.2.3 From 48c092bc9ce79e469d7a8ec9242eefe7fdf1ceff Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Mon, 5 Oct 2020 18:41:50 +0300 Subject: Implement custom icons for articles --- .../apps/content/resources/content/guides/how-to-write-a-guide.md | 2 ++ pydis_site/templates/content/articles.html | 2 +- pydis_site/templates/content/category.html | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md index 8ea438a2..dc822d14 100644 --- a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md +++ b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md @@ -1,6 +1,8 @@ --- title: How to Write a Guide short_description: Learn how to write a guide for this website +icon_class: fas +icon: fa-info --- When you are interested about how to write guide for this site (like this), then you can learn about it here. diff --git a/pydis_site/templates/content/articles.html b/pydis_site/templates/content/articles.html index 363bbb4f..35e5db16 100644 --- a/pydis_site/templates/content/articles.html +++ b/pydis_site/templates/content/articles.html @@ -26,7 +26,7 @@ {% for article, data in content.items %}
    - + {{ data.title }} diff --git a/pydis_site/templates/content/category.html b/pydis_site/templates/content/category.html index c2201745..3dec9259 100644 --- a/pydis_site/templates/content/category.html +++ b/pydis_site/templates/content/category.html @@ -30,7 +30,7 @@ {% for article, data in content.items %}
    - + {{ data.title }} -- cgit v1.2.3 From cee633e9dd1454087ed85ea5c38c93608b2647eb Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Mon, 5 Oct 2020 19:02:38 +0300 Subject: Apply recent changes to article writing guide --- .../content/guides/how-to-write-a-article.md | 78 ++++++++++++++++++++++ .../content/guides/how-to-write-a-guide.md | 66 ------------------ 2 files changed, 78 insertions(+), 66 deletions(-) create mode 100644 pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md delete mode 100644 pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md new file mode 100644 index 00000000..0ad45cc3 --- /dev/null +++ b/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md @@ -0,0 +1,78 @@ +--- +title: How to Write a Article +short_description: Learn how to write a article for this website +icon_class: fas +icon: fa-info +--- + +When you are interested about how to write articles for this site (like this), then you can learn about it here. +PyDis use Markdown (GitHub Markdown) files for articles. + +## Getting Started +Before you can get started with writing a article, you need idea. +Best way to find out is your idea good is to discuss about it in #dev-contrib channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. +It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long article, but then this don't get approved. + +To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). +You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. + +## Creating a File +All articles is located at `site` repository, in `pydis_site/apps/content/resources/content`. Under this is root level articles (.md files) and categories (directories). Learn more about categories in [categories section](#categories). + +When you are writing guides, then these are located under `guides` category. + +At this point, you will need your article name for filename. Replace all your article name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of article in URL. + +## Markdown Metadata +Article files have some required metadata, like title, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: + +```md +--- +title: My Article +short_description: This is my short description. +relevant_links: url1,url2,url3 +relevant_link_values: Text for url1,Text for url2,Text for url3 +--- + +Here comes content of article... +``` + +You can read more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). + +### Fields +- **Name:** Easily-readable name for your article. +- **Short Description:** Small, 1-2 line description that describe what your article explain. +- **Relevant Links and Values:** URLs and values is under different fields, separated with comma. + +## Content +For content, mostly you can use standard markdown, but there is a few addition that is available. + +### IDs for quick jumps +System automatically assign IDs to headers, so like this header will get ID `ids-for-quick-jumps`. + +### Tables +Tables like in GitHub is supported too: + +| This is header | This is too header | +| -------------- | ------------------ | +| My item | My item too | + +### Codeblocks +Also this system supports codeblocks and provides syntax highlighting with `highlight.js`. +To activate syntax highlight, just put language directly after starting backticks. + +```py +import os + +path = os.path.join("foo", "bar") +``` + +## Categories +To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/content/resources/content` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: + +```yml +name: Category name +description: Category description +``` + +Then all Markdown files in this folder will be under this category. diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md deleted file mode 100644 index dc822d14..00000000 --- a/pydis_site/apps/content/resources/content/guides/how-to-write-a-guide.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: How to Write a Guide -short_description: Learn how to write a guide for this website -icon_class: fas -icon: fa-info ---- - -When you are interested about how to write guide for this site (like this), then you can learn about it here. -PyDis use Markdown files for guides, but these files have some small differences from standard Markdown (like defining HTML IDs and classes). - -## Getting Started -First, you have to have a good idea, that match with PyDis theme. We can't accept guides like *How to bake a cake*, -*How to lose weigth*. These doesn't match with PyDis theme and will be declined. Most of guides theme should be server and Python, but there can be some exceptions, when they are connected with PyDis. -Best way to find out is your idea good is to discuss about it in #dev-core channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. -It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long guide, but then this don't get approved. - -To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). -You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. - -## Creating a File -All guides is located at `site` repository, in `pydis_site/apps/guides/resources/guides`. Under this is root level guides (.md files) and categories (directories). Learn more about categories in [categories section](#categories). - -At this point, you will need your guide name for filename. Replace all your guide name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of guide in URL. - -## Markdown Metadata -Guide files have some required metadata, like title, contributors, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: - -```md -Title: My Guide -ShortDescription: This is my short description. -Contributors: person1 - person2 - person3 -RelevantLinks: url1 - url2 - url3 -RelevantLinkValues: Text for url1 - Text for url2 - Text for url3 - -Here comes content of guide... -``` - -You can read more about Markdown metadata [here](https://python-markdown.github.io/extensions/meta_data/). - -### Fields -- **Name:** Easily-readable name for your guide. -- **Short Description:** Small, 1-2 line description that describe what your guide explain. -- **Contributors:** All who have contributed to this guide. One person per-line, and they **have to be at same level**. When you edit guide, add your name to there. -- **Relevant Links and Values:** Links that will be shown at right side. Both key's values have to be at same level, just like for contributors field. - -## Content -For content, mostly you can use standard markdown, but there is a few addition that is available. - -### HTML classes and IDs -To provide HTML classes and/or IDs, this use `{: id="myid" class="class1 class2" }`. When using it at header, place this **right after** title, no space between them. For mutliline items, place them next line after end of block. You can read more about it [here](https://python-markdown.github.io/extensions/attr_list/). - -## Categories -To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/guides/resources/guides` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: - -```yml -name: Category name -description: Category description -``` - -Then all Markdown files in this folder will be under this category. -- cgit v1.2.3 From fc54d5077fc18b148110d2d2911db54dc9839436 Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Tue, 6 Oct 2020 20:42:09 +0300 Subject: Add information about icons to articles writing guide --- .../apps/content/resources/content/guides/how-to-write-a-article.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md index 0ad45cc3..ec89988c 100644 --- a/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md +++ b/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md @@ -43,6 +43,8 @@ You can read more about Markdown metadata [here](https://github.com/trentm/pytho - **Name:** Easily-readable name for your article. - **Short Description:** Small, 1-2 line description that describe what your article explain. - **Relevant Links and Values:** URLs and values is under different fields, separated with comma. +- **Icon class:** `icon_class` field have one of the favicons classes. Default is `fab`. +- **Icon:** `icon` field have favicon name. Default `fa-python`. ## Content For content, mostly you can use standard markdown, but there is a few addition that is available. -- cgit v1.2.3 From 420552591d79ba5662e1a026f385f40157e7dc40 Mon Sep 17 00:00:00 2001 From: ks129 <45097959+ks129@users.noreply.github.com> Date: Sat, 28 Nov 2020 09:58:39 +0200 Subject: Move articles writing guide to PyDis guides directory --- .../content/guides/how-to-write-a-article.md | 80 ---------------------- .../content/guides/pydis-guides/_info.yml | 2 + .../guides/pydis-guides/how-to-write-a-article.md | 80 ++++++++++++++++++++++ 3 files changed, 82 insertions(+), 80 deletions(-) delete mode 100644 pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md create mode 100644 pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml create mode 100644 pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md deleted file mode 100644 index ec89988c..00000000 --- a/pydis_site/apps/content/resources/content/guides/how-to-write-a-article.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: How to Write a Article -short_description: Learn how to write a article for this website -icon_class: fas -icon: fa-info ---- - -When you are interested about how to write articles for this site (like this), then you can learn about it here. -PyDis use Markdown (GitHub Markdown) files for articles. - -## Getting Started -Before you can get started with writing a article, you need idea. -Best way to find out is your idea good is to discuss about it in #dev-contrib channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. -It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long article, but then this don't get approved. - -To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). -You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. - -## Creating a File -All articles is located at `site` repository, in `pydis_site/apps/content/resources/content`. Under this is root level articles (.md files) and categories (directories). Learn more about categories in [categories section](#categories). - -When you are writing guides, then these are located under `guides` category. - -At this point, you will need your article name for filename. Replace all your article name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of article in URL. - -## Markdown Metadata -Article files have some required metadata, like title, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: - -```md ---- -title: My Article -short_description: This is my short description. -relevant_links: url1,url2,url3 -relevant_link_values: Text for url1,Text for url2,Text for url3 ---- - -Here comes content of article... -``` - -You can read more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). - -### Fields -- **Name:** Easily-readable name for your article. -- **Short Description:** Small, 1-2 line description that describe what your article explain. -- **Relevant Links and Values:** URLs and values is under different fields, separated with comma. -- **Icon class:** `icon_class` field have one of the favicons classes. Default is `fab`. -- **Icon:** `icon` field have favicon name. Default `fa-python`. - -## Content -For content, mostly you can use standard markdown, but there is a few addition that is available. - -### IDs for quick jumps -System automatically assign IDs to headers, so like this header will get ID `ids-for-quick-jumps`. - -### Tables -Tables like in GitHub is supported too: - -| This is header | This is too header | -| -------------- | ------------------ | -| My item | My item too | - -### Codeblocks -Also this system supports codeblocks and provides syntax highlighting with `highlight.js`. -To activate syntax highlight, just put language directly after starting backticks. - -```py -import os - -path = os.path.join("foo", "bar") -``` - -## Categories -To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/content/resources/content` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: - -```yml -name: Category name -description: Category description -``` - -Then all Markdown files in this folder will be under this category. diff --git a/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml b/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml new file mode 100644 index 00000000..64111a83 --- /dev/null +++ b/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml @@ -0,0 +1,2 @@ +name: Python Discord Guides +description: Python Discord server and community guides. diff --git a/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md new file mode 100644 index 00000000..ec89988c --- /dev/null +++ b/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md @@ -0,0 +1,80 @@ +--- +title: How to Write a Article +short_description: Learn how to write a article for this website +icon_class: fas +icon: fa-info +--- + +When you are interested about how to write articles for this site (like this), then you can learn about it here. +PyDis use Markdown (GitHub Markdown) files for articles. + +## Getting Started +Before you can get started with writing a article, you need idea. +Best way to find out is your idea good is to discuss about it in #dev-contrib channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. +It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long article, but then this don't get approved. + +To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). +You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. + +## Creating a File +All articles is located at `site` repository, in `pydis_site/apps/content/resources/content`. Under this is root level articles (.md files) and categories (directories). Learn more about categories in [categories section](#categories). + +When you are writing guides, then these are located under `guides` category. + +At this point, you will need your article name for filename. Replace all your article name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of article in URL. + +## Markdown Metadata +Article files have some required metadata, like title, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: + +```md +--- +title: My Article +short_description: This is my short description. +relevant_links: url1,url2,url3 +relevant_link_values: Text for url1,Text for url2,Text for url3 +--- + +Here comes content of article... +``` + +You can read more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). + +### Fields +- **Name:** Easily-readable name for your article. +- **Short Description:** Small, 1-2 line description that describe what your article explain. +- **Relevant Links and Values:** URLs and values is under different fields, separated with comma. +- **Icon class:** `icon_class` field have one of the favicons classes. Default is `fab`. +- **Icon:** `icon` field have favicon name. Default `fa-python`. + +## Content +For content, mostly you can use standard markdown, but there is a few addition that is available. + +### IDs for quick jumps +System automatically assign IDs to headers, so like this header will get ID `ids-for-quick-jumps`. + +### Tables +Tables like in GitHub is supported too: + +| This is header | This is too header | +| -------------- | ------------------ | +| My item | My item too | + +### Codeblocks +Also this system supports codeblocks and provides syntax highlighting with `highlight.js`. +To activate syntax highlight, just put language directly after starting backticks. + +```py +import os + +path = os.path.join("foo", "bar") +``` + +## Categories +To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/content/resources/content` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: + +```yml +name: Category name +description: Category description +``` + +Then all Markdown files in this folder will be under this category. -- cgit v1.2.3 From 82daedc766dc3986dc9ac17ea8a6b3da87a6b1ac Mon Sep 17 00:00:00 2001 From: kosayoda Date: Tue, 23 Mar 2021 23:17:55 +0800 Subject: Simplify content app. Rather than having two views for the base page and all other pages, all pages now use the same view. The view context handler is simplified to take advantage of pathlib features. The markdown folder is now /content/resources/* rather than /content/resources/content/*, as the latter is unnecessary nesting. --- pydis_site/apps/content/resources/_info.yml | 2 + .../content/resources/content/guides/_info.yml | 2 - .../content/guides/pydis-guides/_info.yml | 2 - .../guides/pydis-guides/how-to-write-a-article.md | 80 ---------------------- pydis_site/apps/content/resources/guides/_info.yml | 2 + .../resources/guides/pydis-guides/_info.yml | 2 + .../guides/pydis-guides/how-to-write-a-article.md | 80 ++++++++++++++++++++++ pydis_site/apps/content/urls.py | 2 +- pydis_site/apps/content/utils.py | 42 ++++-------- pydis_site/apps/content/views/__init__.py | 3 +- pydis_site/apps/content/views/page_category.py | 61 +++++++---------- pydis_site/apps/content/views/pages.py | 16 ----- pydis_site/settings.py | 2 +- pydis_site/templates/content/listing.html | 5 +- pydis_site/templates/content/page.html | 1 - 15 files changed, 127 insertions(+), 175 deletions(-) create mode 100644 pydis_site/apps/content/resources/_info.yml delete mode 100644 pydis_site/apps/content/resources/content/guides/_info.yml delete mode 100644 pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml delete mode 100644 pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md create mode 100644 pydis_site/apps/content/resources/guides/_info.yml create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/_info.yml create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/how-to-write-a-article.md delete mode 100644 pydis_site/apps/content/views/pages.py (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 new file mode 100644 index 00000000..4ccdd7e1 --- /dev/null +++ b/pydis_site/apps/content/resources/_info.yml @@ -0,0 +1,2 @@ +name: Pages +description: Guides, articles and pages hosted on the site. diff --git a/pydis_site/apps/content/resources/content/guides/_info.yml b/pydis_site/apps/content/resources/content/guides/_info.yml deleted file mode 100644 index 369f05d4..00000000 --- a/pydis_site/apps/content/resources/content/guides/_info.yml +++ /dev/null @@ -1,2 +0,0 @@ -name: Guides -description: Python and PyDis guides. diff --git a/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml b/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml deleted file mode 100644 index 64111a83..00000000 --- a/pydis_site/apps/content/resources/content/guides/pydis-guides/_info.yml +++ /dev/null @@ -1,2 +0,0 @@ -name: Python Discord Guides -description: Python Discord server and community guides. diff --git a/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md deleted file mode 100644 index ec89988c..00000000 --- a/pydis_site/apps/content/resources/content/guides/pydis-guides/how-to-write-a-article.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: How to Write a Article -short_description: Learn how to write a article for this website -icon_class: fas -icon: fa-info ---- - -When you are interested about how to write articles for this site (like this), then you can learn about it here. -PyDis use Markdown (GitHub Markdown) files for articles. - -## Getting Started -Before you can get started with writing a article, you need idea. -Best way to find out is your idea good is to discuss about it in #dev-contrib channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. -It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long article, but then this don't get approved. - -To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). -You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. - -## Creating a File -All articles is located at `site` repository, in `pydis_site/apps/content/resources/content`. Under this is root level articles (.md files) and categories (directories). Learn more about categories in [categories section](#categories). - -When you are writing guides, then these are located under `guides` category. - -At this point, you will need your article name for filename. Replace all your article name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of article in URL. - -## Markdown Metadata -Article files have some required metadata, like title, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: - -```md ---- -title: My Article -short_description: This is my short description. -relevant_links: url1,url2,url3 -relevant_link_values: Text for url1,Text for url2,Text for url3 ---- - -Here comes content of article... -``` - -You can read more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). - -### Fields -- **Name:** Easily-readable name for your article. -- **Short Description:** Small, 1-2 line description that describe what your article explain. -- **Relevant Links and Values:** URLs and values is under different fields, separated with comma. -- **Icon class:** `icon_class` field have one of the favicons classes. Default is `fab`. -- **Icon:** `icon` field have favicon name. Default `fa-python`. - -## Content -For content, mostly you can use standard markdown, but there is a few addition that is available. - -### IDs for quick jumps -System automatically assign IDs to headers, so like this header will get ID `ids-for-quick-jumps`. - -### Tables -Tables like in GitHub is supported too: - -| This is header | This is too header | -| -------------- | ------------------ | -| My item | My item too | - -### Codeblocks -Also this system supports codeblocks and provides syntax highlighting with `highlight.js`. -To activate syntax highlight, just put language directly after starting backticks. - -```py -import os - -path = os.path.join("foo", "bar") -``` - -## Categories -To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/content/resources/content` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: - -```yml -name: Category name -description: Category description -``` - -Then all Markdown files in this folder will be under this category. diff --git a/pydis_site/apps/content/resources/guides/_info.yml b/pydis_site/apps/content/resources/guides/_info.yml new file mode 100644 index 00000000..369f05d4 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/_info.yml @@ -0,0 +1,2 @@ +name: Guides +description: Python and PyDis guides. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml b/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml new file mode 100644 index 00000000..64111a83 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml @@ -0,0 +1,2 @@ +name: Python Discord Guides +description: Python Discord server and community guides. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-write-a-article.md b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-write-a-article.md new file mode 100644 index 00000000..ec89988c --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-write-a-article.md @@ -0,0 +1,80 @@ +--- +title: How to Write a Article +short_description: Learn how to write a article for this website +icon_class: fas +icon: fa-info +--- + +When you are interested about how to write articles for this site (like this), then you can learn about it here. +PyDis use Markdown (GitHub Markdown) files for articles. + +## Getting Started +Before you can get started with writing a article, you need idea. +Best way to find out is your idea good is to discuss about it in #dev-contrib channel. There can other peoples give their opinion about your idea. Even better, open issue in site repository first, then PyDis staff can see it and approve/decline this idea. +It's good idea to wait for staff decision before starting to write guide to avoid case when you write a long long article, but then this don't get approved. + +To start with contributing, you should read [how to contribute to site](https://pythondiscord.com/pages/contributing/site/). +You should also read our [Git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), because you need to push your guide to GitHub. + +## Creating a File +All articles is located at `site` repository, in `pydis_site/apps/content/resources/content`. Under this is root level articles (.md files) and categories (directories). Learn more about categories in [categories section](#categories). + +When you are writing guides, then these are located under `guides` category. + +At this point, you will need your article name for filename. Replace all your article name spaces with `-` and make all lowercase. Save this as `.md` (Markdown) file. This name (without Markdown extension) is path of article in URL. + +## Markdown Metadata +Article files have some required metadata, like title, description, relevant pages. Metadata is first thing in file, YAML-like key-value pairs: + +```md +--- +title: My Article +short_description: This is my short description. +relevant_links: url1,url2,url3 +relevant_link_values: Text for url1,Text for url2,Text for url3 +--- + +Here comes content of article... +``` + +You can read more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). + +### Fields +- **Name:** Easily-readable name for your article. +- **Short Description:** Small, 1-2 line description that describe what your article explain. +- **Relevant Links and Values:** URLs and values is under different fields, separated with comma. +- **Icon class:** `icon_class` field have one of the favicons classes. Default is `fab`. +- **Icon:** `icon` field have favicon name. Default `fa-python`. + +## Content +For content, mostly you can use standard markdown, but there is a few addition that is available. + +### IDs for quick jumps +System automatically assign IDs to headers, so like this header will get ID `ids-for-quick-jumps`. + +### Tables +Tables like in GitHub is supported too: + +| This is header | This is too header | +| -------------- | ------------------ | +| My item | My item too | + +### Codeblocks +Also this system supports codeblocks and provides syntax highlighting with `highlight.js`. +To activate syntax highlight, just put language directly after starting backticks. + +```py +import os + +path = os.path.join("foo", "bar") +``` + +## Categories +To have some systematic sorting of guides, site support guides categories. Currently this system support only 1 level of categories. Categories live at `site` repo in `pydis_site/apps/content/resources/content` subdirectories. Directory name is path of category in URL. Inside category directory, there is 1 file required: `_info.yml`. This file need 2 key-value pairs defined: + +```yml +name: Category name +description: Category description +``` + +Then all Markdown files in this folder will be under this category. diff --git a/pydis_site/apps/content/urls.py b/pydis_site/apps/content/urls.py index 1406f672..c11b222a 100644 --- a/pydis_site/apps/content/urls.py +++ b/pydis_site/apps/content/urls.py @@ -4,6 +4,6 @@ from . import views app_name = "content" urlpatterns = [ - path("", views.PagesView.as_view(), name='pages'), + path("", views.PageOrCategoryView.as_view(), name='pages'), path("/", views.PageOrCategoryView.as_view(), name='page_category'), ] diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index db502a71..ef02a8cb 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -1,65 +1,49 @@ -import os -from typing import Dict, List, Optional, Union +from pathlib import Path +from typing import Dict, Union import yaml -from django.conf import settings from django.http import Http404 from markdown2 import markdown -def get_category(path: List[str]) -> Dict[str, str]: +def get_category(path: Path) -> Dict[str, str]: """Load category information by name from _info.yml.""" - path = settings.PAGES_PATH.joinpath(*path) if not path.exists() or not path.is_dir(): raise Http404("Category not found.") return yaml.safe_load(path.joinpath("_info.yml").read_text()) -def get_categories(path: Optional[List[str]] = None) -> Dict[str, Dict]: +def get_categories(path: Path) -> Dict[str, Dict]: """Get all categories information.""" categories = {} - if path is None: - categories_path = settings.PAGES_PATH - path = [] - else: - categories_path = settings.PAGES_PATH.joinpath(*path) - for name in categories_path.iterdir(): + for name in path.iterdir(): if name.is_dir(): - categories[name.name] = get_category([*path, name.name]) + categories[name.name] = get_category(path.joinpath(name.name)) return categories -def get_pages(path: Optional[List[str]] = None) -> Dict[str, Dict]: - """Get all root or category pages.""" - if path is None: - base_dir = settings.PAGES_PATH - else: - base_dir = settings.PAGES_PATH.joinpath(*path) - +def get_pages(path: Path) -> Dict[str, Dict]: + """Get all root or category page names and their metadata.""" pages = {} - for item in base_dir.iterdir(): + for item in path.iterdir(): if item.is_file() and item.name.endswith(".md"): md = markdown(item.read_text(), extras=["metadata"]) - pages[os.path.splitext(item.name)[0]] = md.metadata + pages[item.stem] = md.metadata return pages -def get_page(path: List[str]) -> Dict[str, Union[str, Dict]]: +def get_page(path: Path) -> Dict[str, Union[str, Dict]]: """Get one specific page. When category is specified, get it from there.""" - page_path = settings.PAGES_PATH.joinpath(*path[:-1]) - - # We need to include extension MD - page_path = page_path.joinpath(f"{path[-1]}.md") - if not page_path.exists() or not page_path.is_file(): + if not path.exists() or not path.is_file(): raise Http404("Page not found.") html = markdown( - page_path.read_text(), + path.read_text(), extras=[ "metadata", "fenced-code-blocks", diff --git a/pydis_site/apps/content/views/__init__.py b/pydis_site/apps/content/views/__init__.py index 740d98e9..70ea1c7a 100644 --- a/pydis_site/apps/content/views/__init__.py +++ b/pydis_site/apps/content/views/__init__.py @@ -1,4 +1,3 @@ from .page_category import PageOrCategoryView -from .pages import PagesView -__all__ = ["PageOrCategoryView", "PagesView"] +__all__ = ["PageOrCategoryView"] diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index f00a79ee..7e04e2f3 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -1,4 +1,5 @@ import typing as t +from pathlib import Path from django.conf import settings from django.http import Http404 @@ -10,14 +11,18 @@ from pydis_site.apps.content import utils class PageOrCategoryView(TemplateView): """Handles pages and page categories.""" + def dispatch(self, request: t.Any, *args, **kwargs) -> t.Any: + """Conform URL path location to the filesystem path.""" + self.location = Path(self.kwargs.get("location", "")) + self.full_location = settings.PAGES_PATH / self.location + + return super().dispatch(request, *args, **kwargs) + def get_template_names(self) -> t.List[str]: """Checks does this use page template or listing template.""" - location = self.kwargs["location"].split("/") - full_location = settings.PAGES_PATH.joinpath(*location) - - if full_location.is_dir(): + if self.full_location.is_dir(): template_name = "content/listing.html" - elif full_location.with_suffix(".md").is_file(): + elif self.full_location.with_suffix(".md").is_file(): template_name = "content/page.html" else: raise Http404 @@ -28,42 +33,24 @@ class PageOrCategoryView(TemplateView): """Assign proper context variables based on what resource user requests.""" context = super().get_context_data(**kwargs) - location: list = self.kwargs["location"].split("/") - full_location = settings.PAGES_PATH.joinpath(*location) - - if full_location.is_dir(): - context["category_info"] = utils.get_category(location) - context["content"] = utils.get_pages(location) - context["categories"] = utils.get_categories(location) - # Add trailing slash here to simplify template - context["path"] = "/".join(location) + "/" - context["in_category"] = True - elif full_location.with_suffix(".md").is_file(): - page_result = utils.get_page(location) - - if len(location) > 1: - context["category_data"] = utils.get_category(location[:-1]) - context["category_data"]["raw_name"] = location[:-1][-1] - else: - context["category_data"] = {"name": None, "raw_name": None} - + if self.full_location.is_dir(): + context["categories"] = utils.get_categories(self.full_location) + context["category_info"] = utils.get_category(self.full_location) + context["content"] = utils.get_pages(self.full_location) + context["path"] = f"{self.location}/" # Add trailing slash here to simplify template + elif self.full_location.with_suffix(".md").is_file(): + page_result = utils.get_page(self.full_location.with_suffix(".md")) context["page"] = page_result context["relevant_links"] = page_result["metadata"].get("relevant_links", {}) else: raise Http404 - location.pop() - breadcrumb_items = [] - while len(location): - breadcrumb_items.insert( - 0, - { - "name": utils.get_category(location)["name"], - "path": "/".join(location) - } - ) - location.pop() - - context["breadcrumb_items"] = breadcrumb_items + breadcrumb_items = [ + { + "name": utils.get_category(settings.PAGES_PATH / location)["name"], + "path": str(location) + } for location in self.location.parents + ] + context["breadcrumb_items"] = reversed(breadcrumb_items) return context diff --git a/pydis_site/apps/content/views/pages.py b/pydis_site/apps/content/views/pages.py deleted file mode 100644 index 11ac0eeb..00000000 --- a/pydis_site/apps/content/views/pages.py +++ /dev/null @@ -1,16 +0,0 @@ -from django.views.generic import TemplateView - -from pydis_site.apps.content.utils import get_pages, get_categories - - -class PagesView(TemplateView): - """Shows all pages and categories.""" - - template_name = "content/listing.html" - - def get_context_data(self, **kwargs) -> dict: - """Add page and category data to template context.""" - context = super().get_context_data(**kwargs) - context["content"] = get_pages() - context["categories"] = get_categories() - return context diff --git a/pydis_site/settings.py b/pydis_site/settings.py index 0b4d9fd1..3abf556a 100644 --- a/pydis_site/settings.py +++ b/pydis_site/settings.py @@ -287,4 +287,4 @@ SITE_REPOSITORY_OWNER = "python-discord" SITE_REPOSITORY_NAME = "site" SITE_REPOSITORY_BRANCH = "master" -PAGES_PATH = Path(BASE_DIR, "pydis_site", "apps", "content", "resources", "content") +PAGES_PATH = Path(BASE_DIR, "pydis_site", "apps", "content", "resources") diff --git a/pydis_site/templates/content/listing.html b/pydis_site/templates/content/listing.html index 39eae1c2..097cac4f 100644 --- a/pydis_site/templates/content/listing.html +++ b/pydis_site/templates/content/listing.html @@ -16,13 +16,10 @@
    diff --git a/pydis_site/templates/content/page.html b/pydis_site/templates/content/page.html index 3b0ebb5f..433baa69 100644 --- a/pydis_site/templates/content/page.html +++ b/pydis_site/templates/content/page.html @@ -20,7 +20,6 @@
    {% endfor %}
    diff --git a/pydis_site/templates/content/page.html b/pydis_site/templates/content/page.html index a687933d..c3b2285b 100644 --- a/pydis_site/templates/content/page.html +++ b/pydis_site/templates/content/page.html @@ -5,7 +5,7 @@ {% block head %} - + -- cgit v1.2.3 From 9f7e025f2fc590a75bdb5b14aa65d1f0df4e7eb8 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Wed, 24 Mar 2021 01:42:59 +0800 Subject: Update guide to reflect changes in events app. Wording is also improved. --- pydis_site/apps/content/resources/guides/_info.yml | 2 +- .../resources/guides/pydis-guides/_info.yml | 2 +- .../pydis-guides/how-to-contribute-a-page.md | 88 ++++++++++++++++++++++ 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/guides/_info.yml b/pydis_site/apps/content/resources/guides/_info.yml index 369f05d4..59c60a7b 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 -description: Python and PyDis 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 64111a83..7c9a2225 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 -description: Python Discord server and community 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 new file mode 100644 index 00000000..ac663898 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md @@ -0,0 +1,88 @@ +--- +title: How to Contribute a Page +description: Learn how to write and publish a page to this website. +icon_class: fas +icon: fa-info +relevant_links: + Contributing to Site: https://pythondiscord.com/pages/contributing/site/ + Using Git: https://pythondiscord.com/pages/contributing/working-with-git/ +--- + +Pages, which include guides, articles and other static content are stored in markdown files in the `site` repository on Github. +If you are interested in writing or modifying pages seen here on the site, follow the steps below. + +For further assistance and help with contributing pages, send a message to the `#dev-contrib` channel in the Discord server! + +## Prerequisites +Before working on a new page, you have to [setup the site project locally](https://pythondiscord.com/pages/contributing/site/). +It is also a good idea to familiarize yourself with the [git workflow](https://pythondiscord.com/pages/contributing/working-with-git/), as it is part of the contribution workflow. + +Additionally, please submit your proposed page or modification to a page as an [issue in the site repository](https://github.com/python-discord/site/issues), or discuss it in the `#dev-contrib` channel in the server. +As website changes require staff approval, discussing the page content beforehand helps with accelerating the contribution process, and avoids wasted work in the event the proposed page is not accepted. + +## 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`. + +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 +description: Category description +``` + +All the markdown files in this folder will then be under this category. + +## Writing the Page +Files representing pages are in `.md` (Markdown) format, with all-lowercase filenames and spaces replaced with `-` characters. + +Each page must include required metadata, and optionally additional metadata to modify appearance of the page. +The metadata is written in YAML-like key-value pairs, and should be enclosed in triple dashes `---` *at the top of the markdown file*. + +**Example:** +```yaml +--- +title: How to Contribute a Page +description: Learn how to write and publish a page to this website. +icon_class: fas +icon: fa-info +relevant_links: + Contributing to Site: https://pythondiscord.com/pages/contributing/site/ + Using Git: https://pythondiscord.com/pages/contributing/working-with-git/ +--- + +Pages, which include guides, articles and other static content... +``` + +You can learn more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). + +### Required Fields +- **title:** Easily-readable title for your article. +- **description:** Short, 1-2 line description that describes the page. + +### 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` +- **relevant_links:** A YAML dictionary containing `text:link` pairs. See the example above. + +## Extended Markdown + +Apart from standard markdown, certain additions are available: + +### Tables + +| This is header | This is another header | +| -------------- | ---------------------- | +| An item | Another item | +| Big item | Small item | + + +### Codeblock Syntax Highlighting +Syntax highlighting is provided by `highlight.js`. +To activate syntax highlighting, put the language directly after the starting backticks. + +```python +import os + +path = os.path.join("foo", "bar") +``` -- cgit v1.2.3 From 731ff9482ecae7b5293bcfe1512389efd7f17571 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Wed, 24 Mar 2021 13:22:57 +0800 Subject: Improve phrasing and wording of documentation. --- pydis_site/apps/content/resources/_info.yml | 2 +- .../resources/guides/pydis-guides/how-to-contribute-a-page.md | 10 +++++----- pydis_site/apps/content/utils.py | 4 ++-- pydis_site/apps/content/views/page_category.py | 2 +- 4 files changed, 9 insertions(+), 9 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 4ccdd7e1..583cab18 100644 --- a/pydis_site/apps/content/resources/_info.yml +++ b/pydis_site/apps/content/resources/_info.yml @@ -1,2 +1,2 @@ name: Pages -description: Guides, articles and pages hosted on the site. +description: Guides, articles, and pages hosted on the 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 ac663898..8967e7da 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 @@ -8,7 +8,7 @@ relevant_links: Using Git: https://pythondiscord.com/pages/contributing/working-with-git/ --- -Pages, which include guides, articles and other static content are stored in markdown files in the `site` repository on Github. +Pages, which include guides, articles, and other static content, are stored in markdown files in the `site` repository on Github. If you are interested in writing or modifying pages seen here on the site, follow the steps below. For further assistance and help with contributing pages, send a message to the `#dev-contrib` channel in the Discord server! @@ -36,7 +36,7 @@ All the markdown files in this folder will then be under this category. ## Writing the Page Files representing pages are in `.md` (Markdown) format, with all-lowercase filenames and spaces replaced with `-` characters. -Each page must include required metadata, and optionally additional metadata to modify appearance of the page. +Each page must include required metadata, and optionally additional metadata to modify the appearance of the page. The metadata is written in YAML-like key-value pairs, and should be enclosed in triple dashes `---` *at the top of the markdown file*. **Example:** @@ -51,14 +51,14 @@ relevant_links: Using Git: https://pythondiscord.com/pages/contributing/working-with-git/ --- -Pages, which include guides, articles and other static content... +Pages, which include guides, articles, and other static content,... ``` You can learn more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata). ### Required Fields - **title:** Easily-readable title for your article. -- **description:** Short, 1-2 line description that describes the page. +- **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` @@ -67,7 +67,7 @@ You can learn more about Markdown metadata [here](https://github.com/trentm/pyth ## Extended Markdown -Apart from standard markdown, certain additions are available: +Apart from standard Markdown, certain additions are available: ### Tables diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index 17d7db81..6cb15581 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -15,7 +15,7 @@ def get_category(path: Path) -> Dict[str, str]: def get_categories(path: Path) -> Dict[str, Dict]: - """Get all categories information.""" + """Get information for all categories.""" categories = {} for name in path.iterdir(): @@ -38,7 +38,7 @@ def get_pages(path: Path) -> Dict[str, Dict]: def get_page(path: Path) -> Dict[str, Union[str, Dict]]: - """Get one specific page. When category is specified, get it from there.""" + """Get one specific page.""" if not path.exists() or not path.is_file(): raise Http404("Page not found.") diff --git a/pydis_site/apps/content/views/page_category.py b/pydis_site/apps/content/views/page_category.py index 7e04e2f3..7e8fe07d 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -19,7 +19,7 @@ class PageOrCategoryView(TemplateView): return super().dispatch(request, *args, **kwargs) def get_template_names(self) -> t.List[str]: - """Checks does this use page template or listing template.""" + """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(): -- cgit v1.2.3 From 6ccec0d866c44cd7f9789a396ef6ec6cd2cd5df8 Mon Sep 17 00:00:00 2001 From: kosayoda Date: Wed, 24 Mar 2021 19:55:16 +0800 Subject: Replace `markdown2` with `markdown` and `python-frontmatter`. This allows us to properly escape codeblocks within markdown, permalink to headers on a page, and decouples getting metadata from a file and getting generated HTML from the Markdown content. --- Pipfile | 3 +- Pipfile.lock | 43 ++++++++++++++-- .../pydis-guides/how-to-contribute-a-page.md | 59 +++++++++++++++++++++- pydis_site/apps/content/utils.py | 32 ++++++------ pydis_site/apps/content/views/page_category.py | 15 +++--- pydis_site/static/css/content/page.css | 29 ++++++++--- pydis_site/templates/content/base.html | 2 +- pydis_site/templates/content/page.html | 4 +- 8 files changed, 146 insertions(+), 41 deletions(-) (limited to 'pydis_site/apps/content/resources') diff --git a/Pipfile b/Pipfile index 8af6e3ce..c2b87ab4 100644 --- a/Pipfile +++ b/Pipfile @@ -18,7 +18,8 @@ pyyaml = "~=5.1" pyuwsgi = {version = "~=2.0", sys_platform = "!='win32'"} sentry-sdk = "~=0.14" gitpython = "~=3.1.7" -markdown2 = "~=2.3.9" +markdown = "~=3.3.4" +python-frontmatter = "~=1.0" [dev-packages] coverage = "~=5.0" diff --git a/Pipfile.lock b/Pipfile.lock index 3dfb7ec6..4f8bd0d3 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "893ab5cc0b64f7bb87c0304c9fb6eb24b1856c40286fbbdb1a2bf4a0d7a6d39f" + "sha256": "a338a377b64a5d25bf925646c97d932a2d1c783fc8f40d91b6a9ab8f30c2b14e" }, "pipfile-spec": 6, "requires": { @@ -118,6 +118,14 @@ "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", "version": "==2.10" }, + "importlib-metadata": { + "hashes": [ + "sha256:742add720a20d0467df2f444ae41704000f50e1234f46174b51f9c6031a1bd71", + "sha256:b74159469b464a99cb8cc3e21973e4d96e05d3024d337313fedb618a6e86e6f4" + ], + "markers": "python_version < '3.8'", + "version": "==3.7.3" + }, "libsass": { "hashes": [ "sha256:1521d2a8d4b397c6ec90640a1f6b5529077035efc48ef1c2e53095544e713d1b", @@ -136,13 +144,13 @@ ], "version": "==0.20.1" }, - "markdown2": { + "markdown": { "hashes": [ - "sha256:85956d8119fa6378156fef65545d66705a842819d2e1b50379a2b9d2aaa17cf0", - "sha256:fef148e5fd68d4532286c3e2943e9d2c076a8ad781b0a70a9d599a0ffe91652d" + "sha256:31b5b491868dcc87d6c24b7e3d19a0d730d59d3e46f4eea6430a321bed387a49", + "sha256:96c3ba1261de2f7547b46a00ea8463832c921d3f9d6aba3f255a6f71386db20c" ], "index": "pypi", - "version": "==2.3.10" + "version": "==3.3.4" }, "psycopg2-binary": { "hashes": [ @@ -185,6 +193,14 @@ "index": "pypi", "version": "==2.8.6" }, + "python-frontmatter": { + "hashes": [ + "sha256:766ae75f1b301ffc5fe3494339147e0fd80bc3deff3d7590a93991978b579b08", + "sha256:e98152e977225ddafea6f01f40b4b0f1de175766322004c826ca99842d19a7cd" + ], + "index": "pypi", + "version": "==1.0.0" + }, "pytz": { "hashes": [ "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da", @@ -288,6 +304,15 @@ "markers": "python_version >= '3.5'", "version": "==0.4.1" }, + "typing-extensions": { + "hashes": [ + "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918", + "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c", + "sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f" + ], + "markers": "python_version < '3.8'", + "version": "==3.7.4.3" + }, "urllib3": { "hashes": [ "sha256:2f4da4594db7e1e110a944bb1b551fdf4e6c136ad42e4234131391e21eb5b0df", @@ -303,6 +328,14 @@ ], "index": "pypi", "version": "==5.2.0" + }, + "zipp": { + "hashes": [ + "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76", + "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098" + ], + "markers": "python_version >= '3.6'", + "version": "==3.4.1" } }, "develop": { 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 8967e7da..12969ba2 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 @@ -69,18 +69,75 @@ You can learn more about Markdown metadata [here](https://github.com/trentm/pyth Apart from standard Markdown, certain additions are available: +### Abbreviations +HTML `` tags can be used in markdown using this format: + +**Markdown:** +```nohighlight +This website is HTML generated from YAML and Markdown. + +*[HTML]: Hyper Text Markup Language +*[YAML]: YAML Ain't Markup Language +``` + +**Output:** + +This website is HTML +generated from YAML and Markdown. + +--- + +### Footnotes +**Markdown:** +```nohighlight +This footnote[^1] links to the bottom[^custom_label] of the page[^3]. + +[^1]: Footnote labels start with a caret `^`. +[^3]: The footnote link is numbered based on the order of the labels. +[^custom label]: Footnote labels can contain any text within square brackets. +``` + +**Output:** + +This footnote[^1] links to the bottom[^custom label] of the page[^3]. + +[^1]: Footnote labels start with a caret `^`. +[^3]: The footnote link is numbered based on the order of the labels. +[^custom label]: Footnote labels can contain any text within square brackets. + +--- + ### Tables +**Markdown:** +```nohighlight +| This is header | This is another header | +| -------------- | ---------------------- | +| An item | Another item | +``` + +**Output:** + | This is header | This is another header | | -------------- | ---------------------- | | An item | Another item | -| Big item | Small item | +--- ### Codeblock Syntax Highlighting Syntax highlighting is provided by `highlight.js`. To activate syntax highlighting, put the language directly after the starting backticks. +**Markdown:** +````nohighlight +```python +import os + +path = os.path.join("foo", "bar") +``` +```` + +**Output:** ```python import os diff --git a/pydis_site/apps/content/utils.py b/pydis_site/apps/content/utils.py index 0faf722c..11d2b792 100644 --- a/pydis_site/apps/content/utils.py +++ b/pydis_site/apps/content/utils.py @@ -1,9 +1,11 @@ from pathlib import Path -from typing import Dict, Union +from typing import Dict, Tuple +import frontmatter +import markdown import yaml from django.http import Http404 -from markdown2 import markdown +from markdown.extensions.toc import TocExtension def get_category(path: Path) -> Dict[str, str]: @@ -31,29 +33,25 @@ def get_category_pages(path: Path) -> Dict[str, Dict]: for item in path.glob("*.md"): if item.is_file(): - md = markdown(item.read_text(), extras=["metadata"]) - pages[item.stem] = md.metadata + pages[item.stem] = frontmatter.load(item) return pages -def get_page(path: Path) -> Dict[str, Union[str, Dict]]: +def get_page(path: Path) -> Tuple[str, Dict]: """Get one specific page.""" if not path.is_file(): raise Http404("Page not found.") - html = markdown( - path.read_text(encoding="utf-8"), - extras=[ - "metadata", - "fenced-code-blocks", - "highlightjs-lang", - "header-ids", - "strike", - "target-blank-links", - "tables", - "task_list" + metadata, content = frontmatter.parse(path.read_text(encoding="utf-8")) + html = markdown.markdown( + content, + 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="") ] ) - return {"content": str(html), "metadata": html.metadata} + 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 91aed7f0..4a2ed2d6 100644 --- a/pydis_site/apps/content/views/page_category.py +++ b/pydis_site/apps/content/views/page_category.py @@ -35,18 +35,19 @@ class PageOrCategoryView(TemplateView): 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["category_info"] = category context["page_title"] = category["name"] context["page_description"] = category["description"] - context["pages"] = utils.get_category_pages(self.full_location) + context["path"] = f"{self.location}/" # Add trailing slash here to simplify template elif self.full_location.with_suffix(".md").is_file(): - page_result = utils.get_page(self.full_location.with_suffix(".md")) - context["page"] = page_result - context["page_title"] = page_result["metadata"]["title"] - context["page_description"] = page_result["metadata"]["description"] - context["relevant_links"] = page_result["metadata"].get("relevant_links", {}) + 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", {}) else: raise Http404 diff --git a/pydis_site/static/css/content/page.css b/pydis_site/static/css/content/page.css index f46d6b15..57d7472b 100644 --- a/pydis_site/static/css/content/page.css +++ b/pydis_site/static/css/content/page.css @@ -6,11 +6,26 @@ i.has-icon-padding { padding: 0 10px 25px 0; } -pre { - /* - * Style it the same as the tag, since highlight.js does not style - * backgrounds of 
     tags but bulma does, resulting in a weird off-white
-     * border.
-     */
-    background-color: #282c34;
+/*
+ * Move padding padding from 
     tag to hljs  tags so the padding
+ * space is colored the same as the background of hljs  blocks.
+ */
+.content pre {
+    padding: 0;
+}
+
+code.hljs {
+    padding: 1.75em 2em;
+}
+
+/*
+ * Show header permalink on hover.
+ */
+.headerlink {
+    display: none;
+    padding-left: 0.5em;
+}
+
+:is(h1, h2, h3, h4, h5, h6):hover > .headerlink {
+    display: inline;
 }
diff --git a/pydis_site/templates/content/base.html b/pydis_site/templates/content/base.html
index 1508dfb3..19eec5d4 100644
--- a/pydis_site/templates/content/base.html
+++ b/pydis_site/templates/content/base.html
@@ -3,7 +3,7 @@
 
 {% block title %}{{ page_title }}{% endblock %}
 {% block head %}
-
+    
     
     
     
diff --git a/pydis_site/templates/content/page.html b/pydis_site/templates/content/page.html
index 5e820c26..06d74208 100644
--- a/pydis_site/templates/content/page.html
+++ b/pydis_site/templates/content/page.html
@@ -12,7 +12,7 @@
     {% if relevant_links|length > 0 %}
         
    
             
    
-                {{ page.content|safe }}
+                {{ page|safe }}
             
    
             
    
                 
    
@@ -26,6 +26,6 @@
             
    
         
    
     {% else %}
-        
    {{ page.content|safe }}
    
+        
    {{ page|safe }}
    
     {% endif %}
 {% endblock %}
-- 
cgit v1.2.3


From eb308e9ff697c1879f102522ece9bb97e77c5262 Mon Sep 17 00:00:00 2001
From: kosayoda 
Date: Fri, 26 Mar 2021 14:34:49 +0800
Subject: Remove guide reference to `markdown2`.

Now that we use a separate library for frontmatter (which uses pyyaml),
we can simplify the guide and remove the reference to the old markdown
library.
---
 .../content/resources/guides/pydis-guides/how-to-contribute-a-page.md | 4 +---
 1 file changed, 1 insertion(+), 3 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 12969ba2..f258ef74 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
@@ -37,7 +37,7 @@ All the markdown files in this folder will then be under this category.
 Files representing pages are in `.md` (Markdown) format, with all-lowercase filenames and spaces replaced with `-` characters.
 
 Each page must include required metadata, and optionally additional metadata to modify the appearance of the page.
-The metadata is written in YAML-like key-value pairs, and should be enclosed in triple dashes `---` *at the top of the markdown file*.
+The metadata is written in YAML, and should be enclosed in triple dashes `---` *at the top of the markdown file*.
 
 **Example:**
 ```yaml
@@ -54,8 +54,6 @@ relevant_links:
 Pages, which include guides, articles, and other static content,...
 ```
 
-You can learn more about Markdown metadata [here](https://github.com/trentm/python-markdown2/wiki/metadata).
-
 ### Required Fields
 - **title:** Easily-readable title for your article.
 - **description:** Short, 1-2 line description of the page's content.
-- 
cgit v1.2.3