mdmath allows to use Visual Studio Code as a markdown editor capable of typesetting and rendering TeX math. In fact it now reuses the built in markdown viewer. KaTeX works inside as a fast math renderer.
You can install the extension directly from Visual Studio Code Marketplace.
- KaTeX macros are supported. Simply define them by user settings
mdmath.macros
. See FAQ's for details. - Save corresponding HTML source to the file system. The markdown file name is used for this (extension
.html
though). The destination folder is the same, which is the default. You can change this behavior with help of user settingmdmath.savePath
. - Activate
autosave
feature (default:false
), so whenever you are saving the markdown file, its corresponding HTML file is also saved (tomdmath.savePath
). Simply set user settingmdmath.autosave: true
for this.
Simplify the process of authoring and live previewing markdown documents containing math formulas. This extension is a comfortable tool for scientists, engineers and students with markdown as their first choice document format.
- Inline math
- Display math
- Formula numbering
- Inline math with tables
- Works offline.
- Integrated in native markdown viewer. So after installing the extension, TeX math is properly displayed in the markdown preview window.
- Based on markdown-it plugin markdown-it-texmath.
- Using vscode's Markdown Extension API.
- Editor view and Preview are synchronized while scrolling.
- Copy resulting HTML code to the system clipboard.
- Due to markdown-it-texmath's support of different formula delimiters, these are also available and user configurable with mdmath:
'dollars'
(default)- inline:
$...$
- display:
$$...$$
- display + equation number:
$$...$$ (1)
- inline:
'brackets'
- inline:
\(...\)
- display:
\[...\]
- display + equation number:
\[...\] (1)
- inline:
'gitlab'
- inline:
$`...`$
- display:
```math ... ```
- display + equation number:
```math ... ``` (1)
- inline:
'kramdown'
- inline:
$$...$$
- display:
$$...$$
- display + equation number:
$$...$$ (1)
- inline:
Press F1 key inside of Visual Studio Code and type extension
. Choose Extensions: Install Extension
and then select the Markdown+Math
extension from the list.
cd $HOME/.vscode/extensions
git clone https://github.com/goessner/mdmath.git
cd mdmath
npm install
cd %USERPROFILE%\.vscode\extensions
git clone https://github.com/goessner/mdmath.git
cd mdmath
npm install
- Launch VS Code, create or open a markdown file (
.md
). - Open a preview window.
- Typeset in your markdown source window and see the preview window live updating.
- Press Ctrl+K , or run the command
Save Markdown+Math to HTML
to save the corresponding HTML source to the file system. - Press Ctrl+K . or run the command
Clip Markdown+Math to HTML
to copy the corresponding HTML source to the underlying systems clipboard.
// Path to custom stylesheet file (css).
"mdmath.delimiters": "dollars",
"mdmath.macros": {},
"mdmath.savePath": "./${file.name}.html",
"mdmath.autosave": false
markdown-it
: The markdown renderer also used in VS Code.katex
: This is where credits for fast rendering TeX math in HTML go to.clipboardy
: Access the system clipboard (copy/paste).
-
How to define and use macros ?
- Define them in user settings. For example ...
"mdmath.macros": { "\\RR": "\\mathbb{R}", "\\vek": "{\\begin{pmatrix}#1\\\\#2\\end{pmatrix}}" }
- Use them in your markdown document. For example ...
Vectors in $\RR^2$ have a shape of $$\vek{x}{y}$$
-
Are there global predefined macros ?
- No. Macros are user defined with user settings
mdmath.macros
. So they are available in all user specific markdown documents.
- No. Macros are user defined with user settings
-
Can I write the HTML source to a file ?
- Yes. Use the Markdown: Save Markdown+Math to Html command or the key binding (
'ctrl+K ,'
). - The Html file is written to the folder where the markdown file resides in. This is the default.
- You can change the destination folder by specifying a relative path to your working directory with the help of the user setting
mdmath.savePath
. So for an example you might choosemdmath.savePath: "./html/${file.name}.html"
.
- Yes. Use the Markdown: Save Markdown+Math to Html command or the key binding (
-
Can I synchronously let the HTML source file update ?
- Yes. Simply set the user setting
mdmath.autosave: true
for this (default isfalse
). - Now, whenever you save your markdown file, the corresponding Html file is also saved.
- The destination folder
mdmath.savePath
is used for this.
- Yes. Simply set the user setting
-
Formula highlighting is broken ?
- It is implemented only for
$
delimiters at present. $
characters in markdown text are sometimes confused with math delimiters. Enclose them by backticks (`) then.- Formula highlighting is possible only for formulas on a single line. It breaks with every newline character.
- Math highlighting is completely different from LaTeX math parsing.
- It is implemented only for
-
Which functions does KaTeX support ?
- See them listed at KaTeX Supported Functions and KaTeX Support Table.
-
What if I need to use the currency symbol
$
also in my markup ?- It should be safe to use it. If in doubt escape it.
-
What are the restrictions with inline formulas ?
- Whitespace after opening
$
and before closing$
is not allowed. - Numeric character before opening
$
and after closing$
is not allowed. - At least one character (whitespace ?) is required between two consecutive inline formulas.
- Line break inside is not allowed.
- Whitespace after opening
-
What are the restrictions with display formulas ?
- Not allowed inline of text.
- Blank lines before and behind required.
- Restrictions for inline formulas do not apply.
-
Can I use math markup in blockquotes ?
- We can use inline and display formulas in blockquote sections. In order to avoid the blockquote symbol
'>'
being part of a multiline display formula, display formulas have to be written on a single line in blockquote sections. - Opening display formula in blockquote section and closing formula on a line behind the blockquote section resulted in a fatal error until VSCode 1.26.0. Now it is safe to do so.
- We can use inline and display formulas in blockquote sections. In order to avoid the blockquote symbol
-
Can I use math markup in code blocks ?
- No, math markup in code blocks is shown - as expected - as markup. This is consistent now, but in contrast to
mdmath
versions prior to 2.0.
- No, math markup in code blocks is shown - as expected - as markup. This is consistent now, but in contrast to
-
Can I access the HTML source of the markdown file ?
- Yes. Use the Markdown: Clip Markdown+Math to Html command or the key binding (
'ctrl+K .'
). - The markdown preview window has to be opened once for this in order to function properly.
- You need to have the markdown source window activated here (not the preview window!).
- Please note, that the resulting HTML source references 'CDN'-located remote css files. Change those references to local URL's if necessary.
- Yes. Use the Markdown: Clip Markdown+Math to Html command or the key binding (
-
Is PDF output supported ?
- Not directly. In order to create
*.pdf
output from your Markdown you can create a*.html
document first and print it then using aPDF
printer or use Pandoc. - See Compiling Markdown into HTML.
- Not directly. In order to create
-
Can I use custom CSS styles for the preview window ?
- Yes. Set
mdmath.style
in user settings to the location of your custom CSS file. Its path must be relative to this extension root.
- Yes. Set
-
Cannot copy to clipboard on Linux ?
- This may be because the upstream
clipboardy
needsxsel
on Linux. Runsudo apt-get install xsel
to install.
- This may be because the upstream
-
Can we store Latex macros with mdmath ?
- Yes, there is a new section
mdmath.globalMacros
inpackage.json
. Try to expand it with your own macros.
- Yes, there is a new section
The following folks helped to make mdmath
even better.
- elviswolcott: Implemented the feature of directly saving HTML to the file system including
autosave
ability. - colinfang: helped with implementing macros for mdmath 2.3.5.
- lincr: Helped with fixing problems with
mdmath.clipToHtml
under Ubuntu. - TonySFU: Helped with fixing encoding problems with Chinese language under macOS when using
mdmath.clipToHtml
. - floatdrop: Verifying that clipboardy is a better alternative to
copy-paste
by implementing. - zhanglix: Helped with fixing the
newline
bug withgitlab
delimiters.
See changelog.md
Markdown+Math for VS Code is licensed under the MIT License