How to Contribute

Sim-Docs is built with Docusaurus. You can help by fixing mistakes, improving explanations, or adding new pages.

Getting Started

1. Install Node.js

Download and install Node.js if it is not already on your computer.

To check whether it is installed, run:

node --version
npm --version

2. Download Sim-Docs

Clone the repository using HTTPS:

git clone https://github.com/Simbotics/sim-docs.git

If you have set up an SSH key, you can use SSH instead:

git clone git@github.com:Simbotics/sim-docs.git

3. Install the Dependencies

Open the downloaded sim-docs folder in VS Code. In the terminal, run:

npm install

You only need to do this the first time you set up the website or when its dependencies change.

4. Start the Website

Run the local development server:

npm run start

The website will open in your browser. Saved changes normally appear automatically.

tip

Keep the development server running while you edit. Press Ctrl+C in the terminal when you want to stop it.

Editing Documentation

Documentation pages are .md or .mdx files inside the docs folder. Find the page you want to change, edit it, and save the file.

A page normally begins with front matter followed by its title:

---
sidebar_position: 1
---

# Page Title

Your explanation starts here.

sidebar_position controls where the page appears in its sidebar category.

Markdown Cheat Sheet

Markdown adds formatting using a few simple symbols.

Write this	Result
# Main heading	A main page heading
## Section heading	A section heading
### Smaller heading	A smaller heading
**bold text**	bold text
_italic text_	italic text
`code`	code
[Link text](https://example.com)	Link text
	An image
- List item	A bullet-point item
1. Step	A numbered step

Use fenced code blocks for commands or longer code examples:

```bash
npm run start
```

See the Markdown basic syntax guide for more examples.

Adding Images

Place images for a documentation category inside its img folder. For example:

docs/
└── get-ready/
    ├── img/
    │   └── example.png
    └── example-page.mdx

Use a relative path to show the image on the page:

![A useful description of the image](./img/example.png)

Give every image a short, useful description. This helps readers who use screen readers and explains the image if it does not load.

Before Submitting Your Changes

Check the page in your browser and make sure:

• The instructions are easy to follow.
• Headings appear in the correct order.
• Links and images work.
• Commands and filenames are formatted as code.
• There are no obvious spelling mistakes.

Then create a branch, commit your work, push it to GitHub, and open a pull request. See the Version Control guide if you need help.

Advanced Customization

Most contributors only need to edit files in docs. The following areas change the website itself.

Website Colours and Styles

Edit src/css/custom.css to change shared colours and styles. The main light-theme colours are stored under :root, while dark-theme colours are stored under [data-theme="dark"].

Home Page

The home page is built from JavaScript and CSS files inside src/pages and src/components. Check the page locally after making changes because these files affect the website's layout and behaviour.

For more advanced options, see the Docusaurus guides.