Contributing
On this page, we will explain how to contribute to this documentation. This documentation is created using docusaurus, a static-site generator built with react & mdx!
You don't need to know anything about React to contribute, only Markdown & a little bit of HTML is required!Repository
The repository of this documentation is hosted on github:
We would really appreciate contributions to the documentation via a pull request or fork! All tips & tricks can be found in this page!
Structure
The documentation is structured into different parts. The only parts that contributors should edit are the following ones: All other files are reserved for the admins from this documentation!
./docs/
(documentation)./src/pages/
(extra pages, like this one)./blog/
(the blog)
Here you can find even more info about the different parts:
Name | Path | Notes |
---|---|---|
Guides | ./docs/guides/ | The main documentation and guides. It contains many guides for setting up and using Open Ticket. |
Plugins | ./docs/plugins/ | The developer documentation and guides. This will contain all guides about creating Open Ticket plugins and contributing to the bot. |
API Reference | ./docs/reference/ | The API reference. This contains all commands, config variables, classes, types and more! Everything is structured and organized here! |
Blog | ./blog/ | The official blog. If you want to create your own articles, you'll first need to create an "author" with your name! |
Custom Pages | ./src/pages/ | Custom pages. It includes this page and the home page. Please don't edit it without valid reason or contribution. |
Sidebar, Titles & Page Structure
Try to follow the style of the other pages when it comes to naming & styling.
Example: Only use an emoji in the page-name when others in the same category also have it.
Don't use heading level 1
, 5
& 6
. They are too large/small most of the time and don't show up in the table of contents.
Here is an example of how a page should look like:
---
title: The Page Title
description: The Page Description
keywords: [keyword_a, keyword_b, keyword_c] //page keywords (SEO)
sidebar_position: 1 //(optional) position in sidebar
---
<head>
<link rel="apple-touch-icon" href="/img/logo_vertical.png"/>
</head>
//import custom components
import {C,M,ScaleImage,LinkBlock,InlineLink,FlexHorizontal,Divider,Hex,ApiUrl,ApiBlock,StyledTitle} from "@site/src/components/openticket.jsx"
//short description of what this page is about
Lorem Ipsum
## First Category \{#custom-id} //the first large heading
Some content here
### Subcategory //a small subcategory
Some extra content here
### Subcategory //a small subcategory
Some extra content here
## Second Category \{#custom-id} //the second large heading
Some content here
### Subcategory //a small subcategory
Some extra content here
### Subcategory //a small subcategory
Some extra content here
## Third Category \{#custom-id} //the third large heading
Some content here
### Subcategory //a small subcategory
Some extra content here
### Subcategory //a small subcategory
Some extra content here
Markdown & Styling
There is a lot of styling available, here we will list some examples! If you want to use one of these examples, check this page out in the github repository!
I'm normal text
I'm bold text
I'm italic text
I'm code text
There are also a lot of colors. They can be created using the <C color="...">
component!
Try to use colors in combination with bold text for better visibility!
C | Usage (as text) |
---|---|
red | ✅ Use this for very important text! |
orange | ✅ Use this for important text! |
yellow | ❌ Don't use this! It looks a lot like hyperlinks! |
green | ✅ Use this for tips & tricks! |
cyan | ⚠️ This color doesn't have a use case yet! |
blue | ✅ Use this for things that are nice to know! |
purple | ⚠️ This color doesn't have a use case yet! |
pink | ⚠️ This color doesn't have a use case yet! |
black | ❌ Don't use this! It is invisible on most pages! |
gray | ✅ Use this for smaller details! |
brown | ⚠️ This color doesn't have a use case yet! |
C | Usage (as label) |
---|---|
red | ✅ Used for API booleans |
orange | ✅ Used for API functions |
yellow | ✅ Used for API enums |
green | ✅ Used for API numbers |
cyan | ✅ Used for API objects |
blue | ✅ Used for API strings |
purple | ✅ Used for API classes |
pink | ✅ Used for API arrays |
gray | ✅ Used for API interfaces |
brown | ✅ Used for API types |
black | ⚠️ This color doesn't have a use case yet! |
When displaying large amounts of data, you can use lists & tables like these:
Normal List
- Data A
- Data A.1
- Data A.2
- Data B
- Data B.1
- Data B.2
- Data C
- Data C.1
- Data C.2
Numbered List
- Data A
- Data A.1
- Data A.2
- Data B
- Data B.1
- Data B.2
- Data C
- Data C.1
- Data C.2
Mixed List
- Data A
- Data A.1
- Data A.2
- Data B
- Data B.1
- Data B.2
- Data C
- Data C.1
- Data C.2
Checkbox List
- Data A
- Data A.1
- Data A.2
- Data B
- Data B.1
- Data B.2
- Data C
- Data C.1
- Data C.2
Horizontal Table
Column 1 | Column 2 | Column 3 |
---|---|---|
Row 1 | ||
Row 2 | ||
Row 3 |
Vertical Table
Row 1 | Column 1 | Column 2 | Column 3 |
---|---|---|---|
Row 2 | |||
Row 3 | |||
Row 4 |
Code Blocks
There are also code blocks! You can use them to show data with a little bit syntax-highlighting! You can customise the language, title & line numbering!
{
"abc":123,
"hey":"Hello World!"
}
//this is coooooool!
const a = 1
const b = 2
const c = a+b
console.log("hello world",c)
ADDED:
+ something cool
+ very small features
+ a rickroll
REMOVED:
- boring stuff
- old stuff
Admonitions
Admonitions are special notes that deserve extra attention! You can put any other Markdown inside of them (so you can see them as a sort of container)
Use this for giving tips to users!
Use this to show possible warnings or things that might break or are incompatible!
Use this for urgent warnings/notes that require a lot of attention!
Use this for something that deserves attention, but is not urgent!
Use this for something that deserves attention, but is not urgent! (alternative to info
)
Use this for a feature which is experimental or has been recently added to the bot!
Use this for a feature which has been flagged as deprecated and will be removed in an upcoming version!
Use this for discord/discord.js related notes or an invite to our support server!
Use this for urgent security warnings/notes that deserve attention!
Use this for a upcoming features which are planned to be added to the bot!
API Reference Types
- boolean or event
- number or utility
- string
- object
- array
- class
- function
- type
- interface
- enum
Content & Readability
- ✅ All text in the docs needs to be in English.
- ✅ Include enough details to fill the page.
- ✅ Split large pages up in multiple smaller ones.
- ✅ Use Admonitions only when needed! Most of the time, you can also just use colored text!
- ✅ Check your text for grammatical errors before uploading!
- ✅ When you write an article in the blog, make sure it's linked to your name!
And thats it! For more questions, visit our discord server!