Contributing To These Pages¶

You'd like to help us improve these guides? Great! We're always looking for new contributors to help us improve our documentation. There are many ways you can contribute, from writing new guides, improving existing guides, or even just fixing typos.

What Can I Contribute?¶

There are many ways you can contribute to this project. Here are some examples:

Writing new pages
Improving existing pages
Fixing typos
Expanding explanations

How Do I Contribute?¶

Contributing to this project is easy. Just follow these steps:

Fork this repository
Create a new branch for your changes
Make your changes
Commit your changes
Push your changes to your fork
Create a pull request
Wait for your changes to be reviewed and merged
Celebrate!
Repeat steps 2-8 as often as you like

How Should I Write Pages?¶

Basics¶

We have a few guidelines for writing new pages. Please follow these guidelines when writing your page:

Pages should be written in markdown format
Pages should be written in a way that is easy to understand
Pages should be written in a way that is easy to read
Pages should be written in a way that is easy to follow
Pages should be written in a way that is easy to translate
Pages should be written in a way that is easy to maintain
Pages should be written in a way that is easy to update
Pages should be written in a way that is easy to expand
Pages should be written in a way that is easy to improve
That should cover it..

File Location¶

The markdown files for pages need to be placed in the /data/ directory. The file name should be the same as the page title, with all spaces replaced with hyphens. For example, a page titled "Locations in Incartum" would be saved as locations-in-incartum.md.

We have created some directories to help organize the pages. Please place your page in the appropriate directory. If you are unsure where to place your guide, please ask in our Discord server.

Markdown Guidelines¶

You can structure your page any way you see fit, but we do have a few guidelines for writing markdown files to keep everything looks reasonably consistent.

Headings¶

Headings should be used to break up your guide into sections. When you use hashes # to create headings, you should use the following number of hashes for each heading:

# - Top level heading (autogen - do not use in your guide)
## - Second level heading
### - Third level heading
#### - Fourth level heading

These headings are automatically turned into a table of contents on the guide page. This allows users to quickly jump to the section they are interested in.

Code Blocks¶

Code blocks should be used to display code. You can use code blocks to display commands, code snippets, or even entire files. To create a code block, you can use the following syntax:

```text
# This is a code block
```

You can add an optional language identifier to enable syntax highlighting in your code block.

Inline Code¶

Inline code should be used to display code that is part of a sentence. To create inline code, you can use the following syntax:

`This is inline code`

Links¶

Links should be used to link to other pages. To create a link, you can use the following syntax:

[Link Text](https://example.com)

Images¶

Images can be used, but we recommend using them sparingly. They should be linked from a permenant hosting solution (not somewhere that deletes images after x days) and should not be pushed to this repository unless absolutely necessary. To display an image, you can use the following syntax:

![Image Alt Text](https://example.com/image.png)

Tables¶

Tables can be used to display data in a tabular format. To create a table, you can use the following syntax:

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1    | Row 1    | Row 1    |
| Row 2    | Row 2    | Row 2    |
| Row 3    | Row 3    | Row 3    |

Lists¶

Lists can be used to display data in a list format. To create a list, you can use the following syntax:

- List Item 1
- List Item 2
- List Item 3

MkDocs Goodies¶

Since we are using MkDocs for our documentation, we can take advantage of the plugins and extensions that MkDocs has to offer;

AdmonitionsFlowChartsFormattingContent TabsData TablesFootnotesInlineHiliteMark

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow.

Usage

Admonitions follow a simple syntax: a block starts with !!!, followed by a single keyword used as a type qualifier. The content of the block follows on the next line, indented by four spaces:

Admonition

!!! note

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Note