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 monospacedUseto 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
Some content with markdown syntax
.
Some content with markdown syntax
.
Some content with markdown syntax
.
Some content with markdown syntax
.
Some content with markdown syntax
.
Remember that it's :::important
, not ::: important
with a space!
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/>
It has a pretty straightforward syntax.
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>
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>
Page Format
There are a few things you need to take care of:
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.
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.