{"id":13426639,"url":"https://github.com/goessner/mdmath","last_synced_at":"2025-04-12T06:18:40.923Z","repository":{"id":39838629,"uuid":"74764670","full_name":"goessner/mdmath","owner":"goessner","description":"LaTeX Math for Markdown inside of Visual Studio Code.","archived":false,"fork":false,"pushed_at":"2022-08-08T23:19:54.000Z","size":13671,"stargazers_count":756,"open_issues_count":22,"forks_count":55,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-12T06:18:32.250Z","etag":null,"topics":["javascipt","katex","latex","markdown","markdown-math","markdown-viewer","math","mdmath","tex","vscode-extension"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goessner.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-25T14:24:39.000Z","updated_at":"2025-04-10T21:13:55.000Z","dependencies_parsed_at":"2022-09-07T13:21:47.345Z","dependency_job_id":null,"html_url":"https://github.com/goessner/mdmath","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goessner%2Fmdmath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goessner%2Fmdmath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goessner%2Fmdmath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goessner%2Fmdmath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goessner","download_url":"https://codeload.github.com/goessner/mdmath/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525141,"owners_count":21118620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascipt","katex","latex","markdown","markdown-math","markdown-viewer","math","mdmath","tex","vscode-extension"],"created_at":"2024-07-31T00:01:39.773Z","updated_at":"2025-04-12T06:18:40.891Z","avatar_url":"https://github.com/goessner.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Tutorial"],"sub_categories":["Windows Manager"],"readme":"# ![mdmath](https://github.com/goessner/mdmath/raw/master/img/icon.png) Markdown+Math\n\n[![marketplace](https://vsmarketplacebadge.apphb.com/version/goessner.mdmath.svg)](https://marketplace.visualstudio.com/items?itemName=goessner.mdmath)\n[![marketplace](https://vsmarketplacebadge.apphb.com/installs-short/goessner.mdmath.svg)](https://marketplace.visualstudio.com/items?itemName=goessner.mdmath)\n[![License](https://img.shields.io/github/license/goessner/mdmath.svg)](https://github.com/goessner/mdmath/blob/master/LICENSE.txt)\n[![npm](https://img.shields.io/npm/v/mdmath.svg)](https://www.npmjs.com/package/mdmath)\n\n## What is it ...\n\n**mdmath** allows to use *Visual Studio Code* as a markdown editor capable of typesetting and rendering TeX math.K,\nIn fact it now reuses the built in markdown viewer. KaTeX works inside as a fast math renderer.\n\nYou can install the extension directly from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=goessner.mdmath).\n\n### What is new in **mdmath** 2.7.0 ...\n* Different themes for HTML export are supported now. Users can choose\n  * default\n  * minimal\n  * publication (LaTeX style)\n\n  theme in user settings.\n* about *LaTeX style publication theme*: \n   * view [HTML publication](https://goessner.github.io/mdmath/publication.html).\n   * view [PDF publication](https://www.researchgate.net/publication/352151169_Web_Publications_-_LaTeX_Style)\n   * Download [PDF paper](https://goessner.github.io/mdmath/publication.pdf)\n* Commutative diagrams are working now.\n* Insert *Table Of Content* command available. Inject ToC at cursor location via `Insert Table of Content` from Command Palette (\u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e \u003ckbd\u003eT\u003c/kbd\u003e).\n* User notification on HTML export can be suppressed via boolean user setting `Silent` (default: `false`).\n* 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).\n\n## Features\nSimplify the process of authoring and live previewing markdown documents containing math formulas.\nThis extension is a comfortable tool for scientists, engineers and students with markdown as their first choice \ndocument format.\n\n* Inline math\n* Display math (Pandoc compatible)\n* Formula numbering\n* Inline math with tables\n* Works offline.\n* Integrated in native markdown viewer. So after installing the extension, TeX math is properly displayed in the markdown preview window.\n* Based on [markdown-it](https://github.com/markdown-it/markdown-it) plugin [markdown-it-texmath](https://github.com/goessner/markdown-it-texmath).\n* Using vscode's [Markdown Extension API](https://code.visualstudio.com/docs/extensionAPI/api-markdown).\n* Editor view and Preview are synchronized while scrolling.\n* Copy resulting HTML code to the system clipboard.\n* Due to [markdown-it-texmath's](https://github.com/goessner/markdown-it-texmath) support of different formula delimiters, these are also available and user configurable with mdmath:\n  * `'dollars'` (default)\n    * inline: `$...$`\n    * display: `$$...$$`\n    * display + equation number: `$$...$$ (1)`\n  * `'brackets'`\n    * inline: `\\(...\\)`\n    * display: `\\[...\\]`\n    * display + equation number: `\\[...\\] (1)`\n  * `'gitlab'`\n    * inline: ``$`...`$``\n    * display: `` ```math ... ``` ``\n    * display + equation number: `` ```math ... ``` (1)``\n  * `'julia'`\n    * inline: `$...$`  or ``` ``...`` ```\n    * display: `` ```math ... ``` ``\n    * display + equation number: `` ```math ... ``` (1)``\n  * `'kramdown'`\n    * inline: ``$$...$$``\n    * display: `$$...$$`\n    * display + equation number: `$$...$$ (1)`\n\n![mdmath editing](https://github.com/goessner/mdmath/raw/master/./img/mdmath.gif)\n\n## Installation ...\n\n### ... from inside of VSCode\n\nPress \u003ckbd\u003eF1\u003c/kbd\u003e key inside of *Visual Studio Code* and type `extension`. Choose `Extensions: Install Extension` \nand then select the `Markdown+Math` extension from the list.\n\n### ... from Mac \u0026 Linux Command Line\n```\ncd $HOME/.vscode/extensions\ngit clone https://github.com/goessner/mdmath.git\ncd mdmath\nnpm install\n```\n\n### ... from Windows Command Line\n```\ncd  %USERPROFILE%\\.vscode\\extensions\ngit clone https://github.com/goessner/mdmath.git\ncd mdmath\nnpm install\n```\n\n## Usage\n\n* Launch *VS Code*, create or open a markdown file (`.md`).\n* Open a preview window.\n* Typeset in your markdown source window and see the preview window live updating.\n* Press \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e \u003ckbd\u003e,\u003c/kbd\u003e or run the command `Save Markdown+Math to HTML` to save the corresponding HTML source to the file system. \n* Press \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e \u003ckbd\u003e.\u003c/kbd\u003e or run the command `Clip Markdown+Math to HTML` to copy the corresponding HTML source to the underlying systems clipboard.\n* Press \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e \u003ckbd\u003eT\u003c/kbd\u003e or run the command `Insert Table of Content` to insert a generated Table of Content at cursor location.\n\n##  User Settings\n\n###  Default Settings\n```json\n  \"mdmath.delimiters\": \"dollars\",\n  \"mdmath.macros\": {},\n  \"mdmath.macroFile\": \"\",\n  \"mdmath.savePath\": \"./${file.name}.html\",\n  \"mdmath.autosave\": false,\n  \"mdmath.style\": \"\",\n  \"mdmath.theme\": \"default\",\n  \"mdmath.silent\": false,\n  \"mdmath.outerspace\": false\n```\n###  Example Settings\n![mdmath example user settings](https://github.com/goessner/mdmath/raw/master/./img/usersettings.png)\n\n## Dependencies\n\n* [`markdown-it`](https://github.com/markdown-it/markdown-it): The markdown renderer also used in VS Code.\n* [`katex`](https://github.com/Khan/KaTeX): This is where credits for fast rendering TeX math in HTML go to.\n\n## FAQ\n* __How to define my own CSS file for HTML export ?__\n  * 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.\n* __How to define and use macros ?__\n  * Define them in user settings. For example ...\n  ```json\n  \"mdmath.macros\": {\n      \"\\\\RR\": \"\\\\mathbb{R}\",\n      \"\\\\vek\": \"{\\\\begin{pmatrix}#1\\\\\\\\#2\\\\end{pmatrix}}\"\n  }\n  ```\n  * Use them in your markdown document. For example ...\n  ```\n  Vectors in $\\RR^2$ have a shape of\n\n  $$\\vek{x}{y}$$\n  ```\n  * BTW: KaTeX now supports `\\R` natively, so macro `\\RR` makes sense only for demonstration reasons.\n\n* __Macros not working?__\n  * Be sure to have at least version 2.7.4 installed.\n  * Be sure to have closed and opened VSCode again after having changed settings.\n  * Due to possible macro collision with extension [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) disable `\"markdown.extension.math.enabled\": false,` there.\n\n* __How to define macros in a user macro file?__\n  * Create a JSON file containing the macros and define its path in user settings. For example ...\n  ```json\n  \"mdmath.macroFile\": \"c:/myfiles/mymacros.json\"\n  ```\n  * Define the macros the same way as in the user settings.\n  * User macro definition file has priority over user defined macro settings, which are ignored then.\n* __Are there global predefined macros ?__\n  * No. Macros are user defined with user settings `mdmath.macros`. So they are available in all user specific markdown documents.\n* __Can I write the HTML source to a file ?__\n  * Yes. Use the `Markdown: Save Markdown+Math to Html` command or the key binding \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e\u003ckbd\u003e,\u003c/kbd\u003e. \n  * The Html file is written to the folder where the markdown file resides in. This is the default.\n  * 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\"`.\n* __Can I synchronously let the HTML source file update ?__\n  * Yes. Simply set the user setting `mdmath.autosave: true` for this (default is `false`).\n  * Now, whenever you save your markdown file, the corresponding Html file is also saved.\n  * The destination folder `mdmath.savePath` is used for this.\n  * Be sure to have closed and opened VSCode again after having changed settings.\n\n* __Formula highlighting is broken ?__\n  * It is implemented only for `$` delimiters at present.\n  * `$` characters in markdown text are sometimes confused with math delimiters. Enclose them by backticks (`) then.\n  * Formula highlighting is possible only for formulas on a single line. It breaks with every newline character.\n  * Math highlighting is completely different from LaTeX math parsing.\n* __Which functions does KaTeX support ?__\n  * See them listed at [KaTeX Supported Functions](https://khan.github.io/KaTeX/docs/supported.html) and [KaTeX Support Table](https://katex.org/docs/support_table.html).\n* __What if I need to use the currency symbol `$` also in my markup ?__\n  * It should be safe to use it. If in doubt escape it.\n* __What are the restrictions with inline formulas ?__\n  * Whitespace after opening `$` and before closing `$` is not allowed.\n  * Numeric character before opening `$` and after closing `$` is not allowed.\n  * At least one character (whitespace ?) is required between two consecutive inline formulas.\n  * Line break inside is not allowed.\n* __What are the restrictions with display formulas ?__\n  * Not allowed inline of text.\n  * Not allowed inside of tables. Use inline math there instead.\n  * Blank lines before and behind required.\n  * Restrictions for inline formulas do not apply.\n* __Can I use math markup in blockquotes ?__\n  * We can use inline and display formulas in blockquote sections. \n  * Multilevel blockquote sections work as expected.\n* __Can I use math markup in code blocks ?__\n  * 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.\n* __Can I access the HTML source of the markdown file ?__\n  * Yes. Use the `Markdown: Clip Markdown+Math to Html` command or the key binding \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eK\u003c/kbd\u003e\u003ckbd\u003e.\u003c/kbd\u003e. \n  * The markdown preview window has to be opened once for this in order to function properly.\n  * You need to have the markdown source window activated here (not the preview window!). \n  * Please note, that the resulting HTML source references 'CDN'-located remote css files. Change those references to local URL's if necessary.\n* __Is PDF output supported ?__\n  * 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](http://pandoc.org/).\n  * See [Compiling Markdown into HTML](https://code.visualstudio.com/docs/languages/markdown).\n* __Can I use custom CSS styles for the preview window ?__\n  *  Yes. Set `mdmath.style` in user settings to the location of your custom CSS file. Its path must be relative to this extension root.\n* __Can we store Latex macros with mdmath ?__\n  * Yes, there is a new section `mdmath.globalMacros` in `package.json`. Try to expand it with your own macros.\n\n## Thank You\n\nThe following folks helped to make `mdmath` even better.\n* [rjmigliori](https://github.com/rjmigliori): Found naming collision with [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) regarding macros.\n* [elviswolcott](https://github.com/elviswolcott): Implemented the feature of directly saving HTML to the file system including `autosave` ability.\n* [colinfang](https://github.com/colinfang): helped with implementing macros for mdmath 2.3.5.\n* [lincr](https://github.com/LCAR979): Helped with fixing problems with `mdmath.clipToHtml` under Ubuntu.\n* [TonySFU](https://github.com/TonySFU): Helped with fixing encoding problems with Chinese language under macOS when using `mdmath.clipToHtml`.\n* [floatdrop](https://github.com/floatdrop): Verifying that [clipboardy](https://github.com/sindresorhus/clipboardy) is a better alternative to `copy-paste` by implementing.\n* [zhanglix](https://github.com/zhanglix): Helped with fixing the `newline` bug with `gitlab` delimiters.\n\n## Contributing\n\nSee [`.github/CONTRIBUTING.md`](https://github.com/goessner/mdmath/blob/master/.github/CONTRIBUTING.md)\n\n## Changelog\n\nSee [`changelog.md`](https://github.com/goessner/mdmath/blob/master/changelog.md)\n\n## License\n\n*Markdown+Math* for VS Code is licensed under the [MIT License](http://opensource.org/licenses/MIT)\n\n © [Stefan Gössner](https://github.com/goessner)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoessner%2Fmdmath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoessner%2Fmdmath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoessner%2Fmdmath/lists"}