How to write documentation for TruBudget
Why?
As you might have seen, TruBudget stores all relevant documentation in the docs folder of the main repository.
While reading the documentation in Markdown using a dedicated markdown reader is possible and quite easy for people working in tech, user with no tech background can have a hard time reading, and navigating through the documentation. This is why the docs folder in this repo is linked with the TruBudget Website.
When a new TruBudget version is released, the CI has an additional step which publishes the current documentation (in the docs folder) on the TruBudget Website.
What is different to standard Markdown?
The TruBudget Website is build using Docusaurus. A static website generator optimized for publishing documentation. Docusaurus supports the standard Markdown syntax, MDX and React for defining and styling pages. Although sometimes React features might come in handy, avoid them. While MD and MDX is partially supported by GitHub, React features are not.
The Syntax
The TruBudget Documentation heavily uses two features from Docusaurus:
Admonitions are used to provide extra information such as notes, tips, or to make a user conscious about the possible side effects of an operation.
Autogenerated sidebar metadata are used to determine the position of the document in the sidebar. This feature is mostly used when there are multiple folders in the directory.