Skip to main content

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 alt text.

  • 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.

This text is monospacedUse
to add a break line.

We can use blockquotes too.

2 ways to create tables:

HeaderHeader
CellCell
HeaderHeader
CellCell

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

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.

info

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

Cool Stuff

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

Discord Message Components

As most files already have the imports for these, it's not that hard to add them.

First, import the necessary components:

import {
DiscordButton,
DiscordButtons,
DiscordInteraction,
DiscordMessage,
DiscordMessages,
} from "discord-message-components/packages/react";
import "discord-message-components/packages/react/dist/style.css";

import DiscordComponent from "@site/src/components/DiscordComponent";

The div starts like so:

<DiscordComponent>

</DiscordComponent>

<br/>

This is where you list a DiscordMessage.

<DiscordComponent>
<DiscordMessage profile="bob">
Hello!
</DiscordMessage>
</DiscordComponent>

<br/>
BobDotCom10/24/2024
Hello!

It has a pretty straightforward syntax.

tip

Add a <br/> to the end of a component to make the content below it look better.

Slash Commands

To make a message authored by a slash command, do the following:

<DiscordComponent>
<DiscordMessage profile="robocord">
<div slot="interactions">
<DiscordInteraction profile="bob" command>
update
</DiscordInteraction>
</div>
Updated dependencies to the latest version!
</DiscordMessage>
</DiscordComponent>
BobDotComused /update
RobocordBot10/24/2024
Updated dependencies to the latest version!

Buttons

To make a message with buttons, do the following:

<DiscordComponent>
<DiscordMessage profile="robocord">
<div slot="interactions">
<DiscordInteraction profile="bob" command>
work
</DiscordInteraction>
</div>
Work Done!
<div slot="actions">
<DiscordButtons>
<DiscordButton type="primary" emoji="📝">Work More</DiscordButton>
<DiscordButton type="secondary" emoji="🛏️">Sleep</DiscordButton>
</DiscordButtons>
</div>
</DiscordMessage>
</DiscordComponent>
BobDotComused /work
RobocordBot10/24/2024
Work Done!

Page Format

There are a few things you need to take care of:

  1. Make sure that the spelling and grammar is perfect. We have a GitHub action configured that will warn you about spelling errors when you start a pull request. Make sure to commit your changes accordingly.

    As for the grammar, you should try reading the changes you have done and wait for reviews from others.

  2. A common mistake people make is incorrect header style. People often think that the less the important the topic is, the lower it's heading style should be.

    [PAGE STARTS]
    # Topic
    ## Less Important Topic
    ## Subtopic
    [PAGE STARTS]
    # About
    [Introduction]

    ## Installation
    [Content]

    ### Windows
    [Content]

    That's VERY wrong. Here's the correct example:

    [PAGE STARTS]
    [Introduction]
    ## Topic
    ## Less Important Topic
    ### Subtopic
    [PAGE STARTS]
    [Introduction]

    ## About
    [More Information]

    ## Installation
    [Content]

    ### Windows
    [Content]

    Note that the ---s at the beginning have been skipped here.