Contributing to the Guide

This page outlines some of the basic syntax you need to know to contribute to the guide. We recommend you also check out:

Info

We use Docusaurus v2 to generate our guide. All the guide pages are generated from mdx files in the docs/ directory. MDX allows you to use JSX in your markdown content.

Structure

Let's visit the docs/ directory and check its file structure.

We can see various folders and a few files in it. Let's talk a bit about the introduction.mdx file. At the top, you can see something like:

---
title: Introduction
description: ...
sidebar_position: 1
---

Most pages have this at the top. The title defaults to the file name. Since the titles need to be Capitalized according to need while the file names are lowercased (sometimes, the file names are shorter than the title!), we set a title ourselves.

The description field is also important. This is the text shown in an embed when the page's link is shared on Discord, Twitter or other websites that support embedded links. Make sure to give a nice an interesting description!

The sidebar_position field is pretty self-explanatory. It sets the position of the page in the sidebar. Most files in categories do not need this since they are sorted alphabetically.

Markdown Syntax

This page quickly outlines some of the syntax that is used in markdown.

Markdown syntax is pretty easy. You can add **bold**, _italic_ and _underline_ text. You can use ~~strikethrough~~. You can use `inline code blocks`.

    ```python
    print("We can use code blocks like this.")
    ```

You can add [links to other websites](https://pycord.dev). You can add images like this: ![alternate text that describes the image](https://pycord.dev/image.png).

- You can create
- unordered lists like this

1. Or ordered lists
2. Like this

3. If you want markdown to automatically detect what number you are on, you can use `1.`
4. Like this

# Headers

## Go

### Like

#### This

You can even use HTML in Markdown.

<samp>This text is monospaced</samp>
Use <br/> to add a break line.

> We can use blockquotes too.

2 ways to create tables:

<table>
    <tr>
        <th>Header</th>
        <th>Header</th>
    </tr>
    <tr>
        <td>Cell</td>
        <td>Cell</td>
    </tr>
</table>

| Header | Header |
| ------ | ------ |
| Cell   | Cell   |

Here's a line for us to start with.

This line is separated from the one above by two new lines, so it will be a _separate paragraph_.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the _same paragraph_.

We can use emojis too! :joy:

- [x] We can have task lists too
- [ ] This is a task
- [ ] That's not done yet

Preview

Markdown syntax is pretty easy. You can add bold, italic and underline text. You can use ~~strikethrough~~. You can use inline code blocks.

print("We can use code blocks like this.")

You can add links to other websites. You can add images by adding .

You can create
unordered lists like this

Or ordered lists
Like this
If you want markdown to automatically detect what number you are on, you can use 1.
Like this
Headers
Go
Like
This

You can even use HTML in Markdown.

This text is monospacedUse
to add a break line.

We can use blockquotes too.

2 ways to create tables:

Header	Header
Cell	Cell

Header	Header
Cell	Cell

Here's a line for us to start with.

This line is separated from the one above by two new lines, so it will be a separate paragraph.

This line is also a separate paragraph, but... This line is only separated by a single newline, so it's a separate line in the same paragraph.

We can use emojis too! 😂

We can have task lists too
This is a task
That's not done yet

Admonitions

We can add warnings, notes, etc. with the following syntax:

:::note

Some **content** with _markdown_ `syntax`.

:::

:::tip

Some **content** with _markdown_ `syntax`.

:::

:::info

Some **content** with _markdown_ `syntax`.

:::

:::caution

Some **content** with _markdown_ `syntax`.

:::

:::danger

Some **content** with _markdown_ `syntax`.

:::

:::important

Remember that it's `:::important`, not `::: important` with a space!

:::

:::tip Cool Stuff

You can edit an admonition's title by adding text after the `:::` and name, like this!

:::

Preview

note