Markdown+Math

What is it ...

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.

What is new in mdmath 2.4.0 ...

• VScode native clipboard functionality is now used for clipping HTML source to the underlying systems clipboard.
• Support for Julia Markdown is added.
• Dependency of third party node.js modules is drastically reduced.
• User defined CSS style is working now.
• Allow macro definition in a user defined JSON file in addition to macro definition inside of user settings.

Features

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)
  • 'brackets'
    • inline: \(...\)
    • display: \[...\]
    • display + equation number: \[...\] (1)
  • 'gitlab'
    • inline: $`...`$
    • display: ```math ... ```
    • display + equation number: ```math ... ``` (1)
  • 'julia'
    • inline: $...$ or ``...``
    • display: ```math ... ```
    • display + equation number: ```math ... ``` (1)
  • 'kramdown'
    • inline: $$...$$
    • display: $$...$$
    • display + equation number: $$...$$ (1)

Installation ...

... from inside of VSCode

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.

... from Mac & Linux Command Line

cd $HOME/.vscode/extensions
git clone https://github.com/goessner/mdmath.git
cd mdmath
npm install

... from Windows Command Line

cd  %USERPROFILE%\.vscode\extensions
git clone https://github.com/goessner/mdmath.git
cd mdmath
npm install

Usage

• 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.

User Settings

Default Settings

  "mdmath.delimiters": "dollars",
  "mdmath.macros": {},
  "mdmath.macroFile": "",
  "mdmath.savePath": "./${file.name}.html",
  "mdmath.autosave": false,
  "mdmath.style": ""

Example Settings

Dependencies

• markdown-it: The markdown renderer also used in VS Code.
• katex: This is where credits for fast rendering TeX math in HTML go to.

FAQ

• How to define my own CSS file for HTML export ?

  • Define it by the user setting mdmath.style as an absolute URL. So for an example you might choose mdmath.style: "file://c:/mystyle/mystyle.css" with windows.

• 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}$$
  

• How to define macros in a user macro file?

  • Create a JSON file containing the macros and define its path in user settings. For example ...

  "mdmath.macroFile": "c:/myfiles/mymacros.json"

  • Define the macros the same way as in the user settings.
  • User macro definition file has priority over user defined macro settings, which are ignored then.

• 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.

• 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 choose mdmath.savePath: "./html/${file.name}.html".

• Can I synchronously let the HTML source file update ?

  • Yes. Simply set the user setting mdmath.autosave: true for this (default is false).
  • Now, whenever you save your markdown file, the corresponding Html file is also saved.
  • The destination folder mdmath.savePath is used for this.

• 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.

• 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.

• What are the restrictions with display formulas ?

  • Not allowed inline of text.
  • Not allowed inside of tables. Use inline math there instead.
  • 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. Starting with version 2.3.8 display formulas have to be written on a single line in blockquote sections. This might break only rarely some recent documents.

• 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.

• 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.

• 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 a PDF printer or use Pandoc.
  • See Compiling Markdown into HTML.

• 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.

• Cannot copy to clipboard on Linux ?

  • This may be because the upstream clipboardy needs xsel on Linux. Run sudo apt-get install xsel to install.

• Can we store Latex macros with mdmath ?

  • Yes, there is a new section mdmath.globalMacros in package.json. Try to expand it with your own macros.

Thank You

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 with gitlab delimiters.

Contributing

See .github/CONTRIBUTING.md

Changelog

See changelog.md

License

Markdown+Math for VS Code is licensed under the MIT License

© Stefan Gössner