The documentation for all Amuzil projects, open source so all can contribute.
Check it out »
Report Bug
·
Request Feature
Table of Contents
The Amuzil Docs is a documentation site for all Amuzil projects. It is and will probably always be a work in progress, as we are always adding new features to our projects. The documentation is made with Material for MkDocs, a Material Design theme for MkDocs.
We believe that open source is the future, and that everyone should be able to contribute to the projects they use. Documentation is a very important part of any project; a project is useless if no one knows how to use it. By open sourcing the documentation, we hope to achieve the following:
- Better documentation: The documentation is written by the community, for the community. The community will write much better documentation than a small team of developers, as they are the end users of the documentation.
- More contributors: By open sourcing the documentation, we hope to attract more contributors to the project. Contributors can help us improve the documentation, and they can also help us improve the projects themselves.
- Reduced workload: By open sourcing the documentation, we hope to reduce the workload of the developers. The developers can focus on developing the projects, and the community can focus on improving the documentation.
- Open Source: Open source is one of the core pillars of our community. We believe that everyone should be able to contribute to the projects they use, so that they can improve it and learn from it.
- Community: We want to build a community around our projects, and open sourcing the documentation is a great way to do that. It gives active contributors a sense of ownership, and it gives people a reason and way to contribute without necessitating technical knowledge or skills.
This guide is not yet finalised and may not be complete. It is also not yet tested.
Before you begin, ensure you have met the following requirements:
-
-
To check if you have Python installed, run the following command:
python --version
It should return a version number, such as 3.11.0. Ensure that the version number is 3.
-
-
Node.js / (We recommend using NVM (Linux/macOS / Windows) to install Node.js)
-
To check if you have Node.js installed, run the following command:
node --version
It should return a version number, such as 18.11.0. Ensure that the version number is at least 18.
-
-
-
To check if you have PNPM installed, run the following command:
pnpm --version
It should return a version number, such as 7.14.2. Ensure that the version number is at least 7.
-
-
-
To check if you have Git installed, run the following command:
git --version
It should return a version number, such as 2.33.0. Ensure that the version number is at least 2.
-
-
(Windows only) GTK+
While the below guide details specific git commands, you also can (and
probably should) use a GUI for Git.
Options include any JetBrains IDE (
such
as IntelliJ IDEA)
, GitHub Desktop,
or GitKraken.
-
Clone the repo
git clone https://github.com/amuzil/docs.git
-
Create a Python virtual environment and activate it
# All platforms python -m venv venv # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate
-
Install the dependencies
pnpm install
-
Serve the live preview
pnpm serve
This will start a live preview of the site. You can access it at http://localhost:8000.
If you have access to the Insiders version of Material for MkDocs, the installation process is slightly different.
-
Clone the repo
git clone https://github.com/amuzil/docs.git
-
Create a
.envfile and set your Insiders access tokenMKDOCS_MATERIAL_INSIDERS_TOKEN={YOUR_TOKEN}
-
Create a Python virtual environment and activate it
# All platforms python -m venv venv # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate
-
(Windows only) Install LXML binaries
-
Download the latest (CPython) Wheel file to your
venv/Libfolder -
Run the following command:
pip install venv\Lib\{WHEEL_FILE}
-
-
Install the dependencies
pnpm install # Remember to replace {YOUR_TOKEN} with your actual token pip install git+https://{YOUR_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git -
Serve the live preview
pnpm serve:insiders
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue. If you really like the project, consider giving it a star!
We use Gitmoji, which is an emoji guide for Git commit messages. It makes it easier to see what kind of changes have been made at a glance.
To make things easier, check out Gitmoji Plus: Commit Button, a plugin for JetBrains IDEs that adds a button to the commit dialog that allows you to easily add a Gitmoji to your commit message.
While the below guide details specific git commands, you also can (and
probably should) use a GUI for Git.
Options include any JetBrains IDE
(such as IntelliJ IDEA),
GitHub Desktop,
or GitKraken.
-
Fork the Project
-
Create your Feature Branch
git checkout -b feature/amazing-feature
Branch naming guidelines:
- Prefix your branch with the topic. Use lowercase branch names. Replace spaces with hyphens.
- If you are working on a page in the documentation, prefix your branch with
the project that page belongs to. For example, if you are working on
Magus's
installation.mdpage, your branch would bemagus/installation. If you are working on a page that does not belong to a specific project, prefix it withdocs. - If you are working on a blog post, prefix your branch with
blog. - If you are working on anything else, use
feature, or something else if applicable (devcontainer,ci, etc.).
-
Commit your Changes
git commit -m ":sparkles: Add some amazing feature" -
Push to the Branch
git push origin feature/amazing-feature
-
Open a Pull Request
Distributed under the Unlicense. See license.md for more
information.
Main contact: Luka "Mahtaran" Leer
