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).
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, and superscript dagger for adjoint. For example with using a bold font for a matrix:
\mathbf{M}^\mathsf{T} \otimes \mathbf{M}^\dagger
