Before you begin:
- Setup the environment.
- Check out the existing issues and pull requests.
The final page is built using MkDocs, a static site generator written in Python. You need to have Python and its package manager Pip installed.
If you're ready, install the dependencies by using this command in the root of this repo:
pip install -r requirements.txt
Make sure to update regularly by using:
pip install -U -r requirements.txt
In addition to MkDocs, we use Markdownlint and Prettier to keep our Markdown structured and well formatted. You have to have Node.JS installed in order to use it. VS Code extensions are available for both of these. If you use another editor, you may need to change the formatting options, in order for it to use our configurations.
# Install dependencies from package.json
npm i
# Setup husky (commit hooks)
npm run prepare
# Run the linting
npm run lint
The linting is automatically run before each commit to ensure your Markdown is formatted correctly. Committing will be stopped, if it fails. To temporarily bypass this, use the --no-verify
argument while committing.
Once you have MkDocs and our dependencies installed, you can start the development server with the following command:
mkdocs serve
You can then open the page by navigating to http://localhost:8000. The page will automatically reload if you change something. We recommend not to use the integrated Markdown preview in your editor, as MkDocs offers a lot of features that are not available in "vanilla" Markdown.
- Fork the repository
- (optional: Make a new branch in the fork)
- Commit changes to the Fork
- Lint your markdown (
npm run lint
) - Create a pull request (PR)
- Create a new branch from main
- Commit changes to the fork
- Lint your markdown (
npm run lint
) - Create a pull request (PR)
- Once you submit your PR, others from the community will review it with you.
- Your code will also be automatically linted using a GitHub Workflow.
- After that, we may have questions, check back on your PR to keep up with the conversation.
- The guides folder is for any guide on how to do anything, such as, start a community, setup a server jar or using certain functions of a plugin.
- The info folder is used for listing all commands, permissions, config options of plugins etc and explaining what they do. Not for examples of how to use them.
- The images folder is for images in guides and other files.
- Don't use absolute paths for images. MkDocs has problems with them. Always use a relative path.
- Check out the Material MkDocs documentation. Try to use some of the advanced features of it, which are not available in "vanilla" Markdown. Most of the extensions should be enabled.
- Don't use Unicode emojis. Material MkDocs comes bundled with an extensions for emojis and icons. For more information, take a look here.
Congratulations! The whole community thanks you. ✨