👨🏫 Changing Docs🔗
Run this command in IntelliJ's terminal window (at the bottom) to start a live preview of the documentation. It will be available on 127.0.0.1:8000 by default.
--livereloadis an optional argument that determines that only changed files will be re-build. This drastically decreases build time. However, it may lead to inaccurate navigation within your site. Serve without this argument to validate your changes once finished.
You should work with the live preview as the documentation does not just contain plain markdown, there are many custom elements which are only visible in the preview. The preview updates whenever you click outside of IntelliJ or trigger a file save.
Hosting on your entire local network
You can also execute this variation to host the website in your local network. This can be useful for testing changes on different devices but is not needed for most tasks. Make sure the hosting device's firewall exposes the port 8000.
Now go ahead and make your changes. Take a look at the sub-pages of this page for more information about how to write good documentation.
You need to commit your changes once they are done. You can do this with IntelliJ's Git integration.
Here are a few tips how to make good commits:
All docs-only commits need to be prefixed with
[DOCS]. This helps to distinguish them from technical commits that have
a very similar name. Additionally, commit names should be short. If needed, provide more detail in the description.
A commit needs to be atomic which means it only contains changes that belong together. Large changes may also be split into multiple commits. This makes it easier to understand your changes.
Example: Originally you just wanted to fix a spelling mistake, but you also added more examples to a different part of the documentation while doing so. Now you should separate these two (logically different) changes into two separate commits. With other words, don't mix up different changes.