Skip to main content

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:

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

example.mdx
---
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!

CUsage (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!
CUsage (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

  1. Data A
    1. Data A.1
    2. Data A.2
  2. Data B
    1. Data B.1
    2. Data B.2
  3. Data C
    1. Data C.1
    2. Data C.2

Mixed List

  1. Data A
    • Data A.1
    • Data A.2
  2. Data B
    • Data B.1
    • Data B.2
  3. 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 1Column 2Column 3
Row 1
Row 2
Row 3

Vertical Table

Row 1Column 1Column 2Column 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!"
}
test.js
//this is coooooool!
const a = 1
const b = 2
const c = a+b
console.log("hello world",c)
changelog
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)

tip

Use this for giving tips to users!

warning

Use this to show possible warnings or things that might break or are incompatible!

danger

Use this for urgent warnings/notes that require a lot of attention!

info

Use this for something that deserves attention, but is not urgent!

note

Use this for something that deserves attention, but is not urgent! (alternative to info)

experimental

Use this for a feature which is experimental or has been recently added to the bot!

deprecated

Use this for a feature which has been flagged as deprecated and will be removed in an upcoming version!

Discorddiscord

Use this for discord/discord.js related notes or an invite to our support server!

security

Use this for urgent security warnings/notes that deserve attention!

availability

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!