Skip to content

Latest commit

 

History

History
227 lines (193 loc) · 12.2 KB

readme.md

File metadata and controls

227 lines (193 loc) · 12.2 KB
Raw

mdmath Markdown+Math

marketplace marketplace License npm

What is it ...

mdmath allows to use Visual Studio Code as a markdown editor capable of typesetting and rendering TeX math.K, 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.7.0 ...

  • Different themes for HTML export are supported now. Users can choose

    • default
    • minimal
    • publication (LaTeX style)

    theme in user settings.

  • about LaTeX style publication theme:

  • Commutative diagrams are working now.

  • Insert Table Of Content command available. Inject ToC at cursor location via Insert Table of Content from Command Palette (Ctrl+K T).

  • User notification on HTML export can be suppressed via boolean user setting Silent (default: false).

  • Enforce inline math $...$ pair being enclosed by space characters as a guard against misinterpretation of single $'s in normal markdown via user setting Outerspace (default: false for backward compatibility).

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 (Pandoc compatible)
  • 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)

mdmath editing

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.
  • Press Ctrl+K T or run the command Insert Table of Content to insert a generated Table of Content at cursor location.

User Settings

Default Settings

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

Example Settings

mdmath example user 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}$$
    • BTW: KaTeX now supports \R natively, so macro \RR makes sense only for demonstration reasons.

  • Macros not working?

    • Be sure to have at least version 2.7.4 installed.
    • Be sure to have closed and opened VSCode again after having changed settings.
    • Due to possible macro collision with extension Markdown All In One disable "markdown.extension.math.enabled": false, there.

  • 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.
    • Be sure to have closed and opened VSCode again after having changed settings.

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

  • 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.
    • Multilevel blockquote sections work as expected.

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

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

  • rjmigliori: Found naming collision with Markdown All In One regarding macros.
  • 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