diff options
author | 2021-03-26 14:40:59 +0800 | |
---|---|---|
committer | 2021-03-26 14:40:59 +0800 | |
commit | 494c63a51a778253e8f90868338d42bd41a700a9 (patch) | |
tree | b48cf80d9b5af914e058d5bd0c616f81972e040b /pydis_site/apps/content/resources | |
parent | Merge pull request #427 from python-discord/ks123/dewikification/event-pages (diff) | |
parent | Remove guide reference to `markdown2`. (diff) |
Merge pull request #393 from ks129/guides-app
Dewikification - Create content app
Diffstat (limited to 'pydis_site/apps/content/resources')
4 files changed, 149 insertions, 0 deletions
diff --git a/pydis_site/apps/content/resources/_info.yml b/pydis_site/apps/content/resources/_info.yml new file mode 100644 index 00000000..583cab18 --- /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/guides/_info.yml b/pydis_site/apps/content/resources/guides/_info.yml new file mode 100644 index 00000000..59c60a7b --- /dev/null +++ b/pydis_site/apps/content/resources/guides/_info.yml @@ -0,0 +1,2 @@ +name: 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 new file mode 100644 index 00000000..7c9a2225 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/_info.yml @@ -0,0 +1,2 @@ +name: Python Discord Guides +description: Guides related to the Python Discord server and community. diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md new file mode 100644 index 00000000..f258ef74 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/pydis-guides/how-to-contribute-a-page.md @@ -0,0 +1,143 @@ +--- +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 the appearance of the page. +The metadata is written in YAML, 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,... +``` + +### Required Fields +- **title:** Easily-readable title for your article. +- **description:** Short, 1-2 line description of the page's content. + +### Optional Fields +- **icon_class:** Favicon class for the category entry for the page. Default: `fab` +- **icon:** Favicon for the category entry for the page. Default: `fa-python` <i class="fab fa-python is-black" aria-hidden="true"></i> +- **relevant_links:** A YAML dictionary containing `text:link` pairs. See the example above. + +## Extended Markdown + +Apart from standard Markdown, certain additions are available: + +### Abbreviations +HTML `<abbr>` 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 <abbr title="Hyper Text Markup Language">HTML</abbr> +generated from <abbr title="YAML Ain't Markup Language">YAML</abbr> 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 | + +--- + +### 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 + +path = os.path.join("foo", "bar") +``` |