Use of Jade, HTML, and Markdown

While Markdown is the preferred language for writing the docs, Jade and HTML and still used in the project. The use of Jade, HTML, and Markdown are explained below.

Jade

Jade is solely used for breaking up the website into modular components and gluing the relevant parts together to generate the static web pages.

HTML

The HTML files are not created manually. Instead, they are generated from the Jade and Markdown files using the make command. For any changes to the site, edit the relevant Jade and Markdown files, not the generated HTML file. Any changes to HTML files will be overwritten when the make command is run.

Refer the next section on use of HTML in the Markdown files.

Markdown

Whenever possible, all documentation should be written in Markdown. However, under certain circumstances, HTML may be used within Markdown code.

HTML may be used with Markdown under the following conditions:

1. Use of tables with complex content
   While the Markdown table syntax works well for simple tabular data, it becomes unpredictable with complex content within it. HTML table may be used in place of Markdown table.
2. Use of HTML element with attributes
   Since Markdown does not support specification of element attributes, HTML maybe be used in its place.
3. Limitations in the Markdown parser
   If, for some reason, the HTML code is not being generated as expected from a particular piece of Markdown, HTML may be used instead of the problematic Markdown code.

Tips

1. Keep the Markdown files "maximum-markdown, minimum-html".
2. If the opening tag in the Markdown file is a block-level element, the tag should be moved to the Jade file which includes the Markdown file.
3. Markdown code does not work within block-level elements.
4. Markdown code works within inline elements.
5. Any code within backticks are interpreted literally.
6. Refer existing doc files for usage examples and guidelines.