-
Notifications
You must be signed in to change notification settings - Fork 115
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 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, stick to those subsets for 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.
TODO: Provide a bunch of examples of what to do, and what not to do, in authored content.