How to Contribute a Page

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. It is also a good idea to familiarize yourself with the git workflow, 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, 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.

Page Categories

Nested folders represent page categories on the website. Each folder under the root folder must include a _info.yml file with the following:

title: Category name
description: Category description
icon: fas fa-folder # Optional

All the markdown files in this folder will then be under this category.

Having the Category Also Be a Page

In order to make categories a page, just create a page with the same name as the category folder in the category's parent directory.

guides
├── contributing.md
├── contributing
│   ├── _info.yml
│   └── bot.md
└── _info.yml

In the above example, www.pythondiscord.com/guides/ will list Contributing as a category entry with information from contributing/_info.yml.

However, www.pythondiscord.com/guides/contributing will render contributing.md rather than show the category contents. A dropdown menu will be automatically generated in the top right corner of the page listing the children of the category page.

Therefore, www.pythondiscord.com/guides/contributing/bot will then render bot.md, with backlinks to contributing.md.

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:

---
title: How to Contribute a Page
description: Learn how to write and publish a page to this website.
icon: fas fa-info
relevant_links:
    Contributing to Site: https://pythondiscord.com/pages/guides/pydis-guides/contributing/site/
    Using Git: https://pythondiscord.com/pages/guides/pydis-guides/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: Icon for the category entry for the page. Default: fab fa-python
  • relevant_links: A YAML dictionary containing text:link pairs. See the example above.
  • toc: A number representing the smallest heading tag to show in the table of contents. See: Table of Contents

Working with dark mode

If your article includes images, you can apply a few classes for a better experience for readers using dark mode.

Add a white background to an image

Use the has-dark-mode-background class to apply a white background to your image, so it can be read easily in dark mode.

![image alt text](/path/to/my/image.png){: class="has-dark-mode-background" }

Alternate images for each mode

If you can provide two images, suited for each of the light and dark modes specifically, you can use the light-image and dark-image classes to have the correct image be used depending on the mode.

![image alt text](/path/to/my/image_light.png){: class="light-image" }
![image alt text](/path/to/my/image_dark.png){: class="dark-image" }

This way, when the reader is in light mode, only image_light.png is shown, and when the reader is in dark mode, only image_dark.png is shown.

All images with light-image class are hidden in dark mode and all images with dark-image class are hidden in light mode.

Extended Markdown

Apart from standard Markdown, certain additions are available:

Abbreviations

HTML <abbr> tags can be used in markdown using this format:

Markdown:

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:

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 footnote1 links to the bottom3 of the page2.


Tables

Markdown:

| 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:

```python
import os

path = os.path.join("foo", "bar")
```

Output:

import os

path = os.path.join("foo", "bar")

HTML Attributes

To add HTML attributes to certain lines/paragraphs, see this page for the format and where to put it.

This can be useful for setting the image size when adding an image using markdown (see the Image Captions section for an example), or for adding bulma styles to certain elements (like the warning notification here).
This should be used sparingly, as it reduces readability and simplicity of the article.


Image Captions

To add an image caption, place a sentence with italics right below the image link

Markdown:

![Summer Code Jam 2020](/static/images/events/summer_code_jam_2020.png){: width="400" }
*Summmer Code Jam 2020 banner with event information.*

Output:

Summer Code Jam 2020 Summer Code Jam 2020 banner with event information.

Note: To display a regular italicized line below an image, leave an empty line between the two.


Table of Contents

In order to show the table of contents on a page, simply define the toc key in the page metadata.

The value of the toc key corresponds to the smallest heading to list in the table of contents. For example, with markdown content like this:

# Header 1
words
### Header 3
more words
# Another Header 1
## Header 2
even more words

and toc: 2 in the page metadata, only Header 1, Another Header 1 and Header 2 will be listed in the table of contents.

To use a custom label in the table of contents for a heading, set the data-toc-label attribute in the heading line. See HTML Attributes for more information.

# Header 1 {: data-toc-label="Header One" }

Tips

Nested/Unhighlighted Code Blocks

To nest code blocks, increase the number of ticks in the outer block by 1. To remove highlighting from code blocks (ie. no dark background), you can use the nohighlight language.

````nohighlight
```python
print("Some inner code block text.")
```
````

Images in Lists

To properly indent images in lists, keep the image on the line directly after the previous line and add <br> to the end of the text, like this:

1. List item text one.<br>
![Image text one](image/link/one)

2. List item text two.<br>
![Image text two](image/link/two)

Keeping Text In The Same Paragraph

You can also use <br> to break lines while keeping them in the same paragraph (avoiding the vertical spacing added between paragraphs).

##### Same line, same paragraph
Line A
Line B

##### Different line, different paragraph
Line A

Line B

##### Different line, same paragraph
Line A<br>
Line B

  1. Footnote labels start with a caret ^

  2. The footnote link is numbered based on the order of the labels. 

  3. Footnote labels can contain any text within square brackets.