Our docs are going to be markdown files, however it may be not enough to stick to the vanilla MD. There might be need for non-standard sections like metadata at the beginning of each file (organizing structure), or occasional html section.

• explain all non-vanilla MD features
• decide if we need any non-standard sections for files