Markdown and LaTeX guidelines
This project uses Markdown and LaTeX extensively, such as for the katas and the Q# standard library documentation.
There are various 'flavors' of these syntaxes, as well as different libraries used in different environments in which content is rendered. For example, VS Code's rendering libraries are different to those used on https://quantum.microsoft.com/. In order to ensure consistency a common subset and some content guidelines should be adhered to, which is the goal of this document.
The markdown package marked and the LaTeX package MathJax are two
of the most popular libraries. However, VS Code uses the markdown-it
package for Markdown, and the KaTeX package for LaTeX (via its markdown-it plugin
@vscode/markdown-it-katex. These are known for being fast,
lightweight, and adhering closely to the documented standards.
The syntax supported by the CommonMark markdown spec can be seen at https://spec.commonmark.org/0.31.2/
The GitHub flavored Markdown spec (which extends CommonMark) can be seen at https://github.github.com/gfm/
The list of LaTeX functions that KaTeX supports can be seen at https://katex.org/docs/supported.
As CommonMark is a subset set of GitHub Flavored Markdown, and KaTeX supports a smaller set of functions
that MathJax, sticking to those subsets will ensure maximum compatibility.
To verify content will render correctly in those libraries, the below online tools can be used:
- Render Markdown via
markdown-itat https://markdown-it.github.io/ - Render LaTeX via
katexat https://katex.org/#demo
Alternatively, author and build your content, then view it locally in the Q# Playground. (See the README for more details).
HTML included in Markdown has some simple rules, but with some surprising implications if not familiar with them. These are summarized in the CommonMark spec in the section at https://spec.commonmark.org/0.31.2/#html-blocks, but some guidelines for simplicity.
-
DONT include blank lines within inline HTML blocks. Per the
End condition:rules in items 6 & 7 in the spec linked to above, this indicates the end of an HTML blocks. - Put the opening HTML tag on its own line. A surprising implication of bullet 6 in the linked to rules, is that
<div>Some content</div>is parsed differently than<span>Some content</span>when included on one line (in adivand other block tags, theSome contentis passed through as-is, whereas for other tags the content following a tag is parsed as Markdown).
To summarize the above rules, write inline HTML similar to the below:
<span id='foo'>
If this content was on the same line as the above opening tag, it would be parsed as Markdown.
<!-- If this was a blank line, it would indicate the end of this HTML block -->
</span>
This is Markdown again, as it follows the first blank line after the opening HTML tag.
Without using the \text macro, spacing can be odd. For example, SWAP = [ \dots ] renders as:
Whereas \text{SWAP} = [ \dots ] renders as:
Trailing breaks in matrices can add an empty row in some libraries, for example \frac{1}{2}\begin{bmatrix} 1\\\ 1\\\ 1\\\ \end{bmatrix} renders as:
Whereas \frac{1}{2} \begin{bmatrix} 1 \\ 1 \\ 1 \end{bmatrix} renders as:
See prior example, where \\\ adds padding to the start of the next row, versus just using \\
Using \mid often causes unwanted spacing. For example, see the difference in the below equation when it
is used compared to just using the | character.
\ket{\psi} = \mid \phi \rangle \implies \braket{\phi | \pi} = \braket{\pi \mid \phi }
See the prior example. The \ket, \bra, and \braket macros are well supported and should be preferred over
"hand authoring" via \rangle etc.
Use a superscript sans-serif T for transpose, superscript dagger for adjoint, and superscript asterisk for conjugate. For example with using a bold font for a matrix:
\mathbf{M}^\mathsf{T} \otimes \mathbf{M}^\dagger \otimes \mathbf{M}^*
