From e3e3ab1cd63d2cb189d0d6ca93fa925abb2da23a Mon Sep 17 00:00:00 2001 From: Stefan Goessner Date: Tue, 13 Nov 2018 09:38:45 +0100 Subject: [PATCH] Version 2.3.5 --- changelog.md | 10 ++-- css/texmath.css | 13 ++++- css/vscode-texmath.css | 17 ++++++- extension.js | 109 ++++++++++++++++++++++------------------- package.json | 26 ++++++---- readme.md | 55 +++++++++++++++++---- triangle.html | 41 ++++++++++++++++ triangle.md | 4 +- 8 files changed, 196 insertions(+), 79 deletions(-) create mode 100644 triangle.html diff --git a/changelog.md b/changelog.md index 8f559f5..6dbe9a6 100644 --- a/changelog.md +++ b/changelog.md @@ -1,9 +1,11 @@ ## CHANGELOG -### [2.3.4]() (Awaiting Review) on October 25, 2018 -* Command to save HTML to file -* Autosave option for saving HTML when Markdown file is changed -* Ability to configure where HTML files are saved +### [2.3.5]() on October 25, 2018 +* Implemented macros supported by KaTeX. +* Command to save HTML to file. +* Autosave option for saving HTML when Markdown file is changed. +* Ability to configure where HTML files are saved. +* `katex` dependency upgrade to `0.10.0`. ### [2.3.3]() on September 07, 2018 * Add support for [Kramdown](https://kramdown.gettalong.org/) . Simply write `"mdmath.delimiters": "kramdown"` into your user settings for activating it. Please note, that syntax highlighting is only properly supported with `dollars`. diff --git a/css/texmath.css b/css/texmath.css index 77a69b2..de9d275 100644 --- a/css/texmath.css +++ b/css/texmath.css @@ -1,13 +1,22 @@ /* style for html inside of browsers */ -.katex { font-size: 1em !important; } /* align KaTeX font-size to surrounding text */ +/* align KaTeX font-size to surrounding text */ +.katex { font-size: 1em !important; } +/* supress effect of display formulas with eqno having bigger margin */ +.katex-display { margin:0 !important; } +/* overwrite github-markdown.css asymmetric margin values */ +.markdown-body blockquote, .markdown-body dl, .markdown-body ol, .markdown-body p, .markdown-body pre, .markdown-body table, .markdown-body ul { + margin-top: 8px; + margin-bottom: 8px; +} eq { display: inline-block; } -eqn { display: block} +eqn { display: block; margin: 0; } section.eqno { display: flex; flex-direction: row; align-content: space-between; align-items: center; + } section.eqno > eqn { width: 100%; diff --git a/css/vscode-texmath.css b/css/vscode-texmath.css index cf3140e..983c35a 100644 --- a/css/vscode-texmath.css +++ b/css/vscode-texmath.css @@ -1,6 +1,21 @@ p { text-align: justify; } -table, figure { +table { + display: table !important; + width: auto !important; + margin-left: auto !important; + margin-right: auto !important; + border-collapse: collapse !important; +} + +table th, table td { + border-left: none !important; + border-right: none !important; + border-top: 1px solid #000 !important; + border-bottom: 1px solid #000 !important; +} + +figure { margin: 0.5em auto; } figure > img { diff --git a/extension.js b/extension.js index 290d6de..e4be41e 100644 --- a/extension.js +++ b/extension.js @@ -5,10 +5,10 @@ 'use strict'; const vscode = require('vscode'), - clipTmpl = (html,usrcss) => ` - - - + htmlTmpl = (html,usrcss) => ` + + + ${usrcss ? `` : ''} @@ -18,89 +18,96 @@ ${html} // this method is called when extension is activated .. exports.activate = function activate(context) { + let mdit = null, + cb = null, + mkdirp = null, + watchingFs = false; + const kt = require('katex'), tm = require('markdown-it-texmath').use(kt), path = require('path'), fs = require('fs'), - mkdirp = require('mkdirp').sync, cfg = (key) => vscode.workspace.getConfiguration('mdmath')[key], delimiters = cfg('delimiters') || 'dollars', + macros = JSON.parse(JSON.stringify(cfg('macros'))), // wondering why this JSON stuff is necessary + options = Object.keys(macros).length !== 0 ? {delimiters,macros} : {delimiters}, runIf = (cond, f) => { return () => { cond() && f() } }, infoMsg = (msg) => { - vscode.window.showInformationMessage(`Markdown + Math: ${msg}`); + vscode.window.showInformationMessage(`Markdown + Math: ${msg}`); }, errMsg = (msg) => { - vscode.window.showErrorMessage(`Markdown + Math: ${msg}`); + vscode.window.showErrorMessage(`Markdown + Math: ${msg}`); }, makeHTML = () => { - const doc = vscode.window.activeTextEditor && vscode.window.activeTextEditor.document; - if (!doc || doc.languageId !== 'markdown') - return infoMsg('Active document is no markdown source document!'); - if (!mdit) - return infoMsg('Corresponding markdown preview document needs to be opened at least once!'); + const doc = vscode.window.activeTextEditor + && vscode.window.activeTextEditor.document; + if (!doc || doc.languageId !== 'markdown') + return infoMsg('Active document is no markdown source document!'); + if (!mdit) + return infoMsg('Corresponding markdown preview document needs to be opened at least once!'); - return clipTmpl(mdit.render(doc.getText())) - + return htmlTmpl(mdit.render(doc.getText())) }, outputLocationOf = (fsPath) => { - const root = vscode.workspace.getWorkspaceFolder(fsPath) || vscode.workspace.rootPath, - parsed = path.parse(fsPath), - savePath = cfg('savePath') - .replace('${file.name}', parsed.name) - .replace('${file.ext}', parsed.ext), - out = savePath.startsWith('/') ? path.resolve(root, `.${savePath}`) : path.resolve(parsed.dir, savePath); + const root = vscode.workspace.getWorkspaceFolder(fsPath) || vscode.workspace.rootPath, + parsed = path.parse(fsPath), + savePath = cfg('savePath') + .replace('${file.name}', parsed.name) + .replace('${file.ext}', parsed.ext), + out = savePath.startsWith('/') ? path.resolve(root, `.${savePath}`) : path.resolve(parsed.dir, savePath); - return path.isAbsolute(out) ? out : path.resolve(parsed.dir, `./${parsed.name}.html`); + return path.isAbsolute(out) ? out : path.resolve(parsed.dir, `./${parsed.name}.html`); }, clip = () => { - if (!cb) cb = require('clipboardy'); - cb.write(makeHTML()) - .then(()=>infoMsg('Html copied to clipboard!'), - (err)=>errMsg('Html copying to clipboard failed: ' + err.message)); + if (!cb) cb = require('clipboardy'); + cb.write(makeHTML()) + .then(()=>infoMsg('Html copied to clipboard!'), + (err)=>errMsg('Html copying to clipboard failed: ' + err.message)); }, save = (uri) => { - try { - uri = uri || vscode.window.activeTextEditor._documentData._uri; + try { + uri = uri || vscode.window.activeTextEditor.document.uri; + if (!watchingFs) // lazy activate fileSystemWatcher ... ! + watchingFs = watch(vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(path.dirname(uri.fsPath), '**/*.md'))); + const dest = outputLocationOf(uri.fsPath); - + + if (!mkdirp) mkdirp = require('mkdirp').sync; mkdirp(path.parse(dest).dir); fs.writeFileSync(dest, makeHTML(), 'UTF-8'); infoMsg(`Html saved to ${dest}!`); - } catch (err) { + } catch (err) { errMsg('Saving html failed: ' + err.message); - } - + } + }, + watch = (watcher) => { + const autosave = runIf(() => { return cfg('autosave') }, save); + watcher.onDidChange(autosave); + watcher.onDidCreate(autosave); + watcher.onDidDelete((uri) => { + try { + const dest = outputLocationOf(uri.fsPath); + fs.unlinkSync(dest); + infoMsg(`Removed ${dest}.`); + } catch (err) { + errMsg('Removing file failed: ' + err.message); + } + }); + return true; }; - let mdit = null, - cb = null; - - ((watcher) => { - const autosave = runIf(() => { return cfg('autosave') }, save); - watcher.onDidChange(autosave); watcher.onDidCreate(autosave); - watcher.onDidDelete((uri) => { - try { - const dest = outputLocationOf(uri.fsPath); - fs.unlinkSync(dest); - infoMsg(`Removed ${dest}.`); - } catch (err) { - errMsg('Removing file failed: ' + err.message); - } - }); - - })(vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.workspace.rootPath, '**/*.md'))); - context.subscriptions.push(vscode.commands.registerCommand('extension.clipToHtml', clip)); - context.subscriptions.push(vscode.commands.registerCommand('extension.renderToHtml', save)); + context.subscriptions.push(vscode.commands.registerCommand('extension.saveToHtml', save)); + return { extendMarkdownIt: function(md) { - return (mdit = md).use(tm, {delimiters:delimiters}); + return (mdit = md).use(tm, options); } } } diff --git a/package.json b/package.json index 9084e32..71ef84d 100644 --- a/package.json +++ b/package.json @@ -2,8 +2,8 @@ "name": "mdmath", "displayName": "Markdown+Math", "description": "LaTeX Math for Markdown", - "icon": "img/icon.png", - "version": "2.3.4", + "icon": "./img/icon.png", + "version": "2.3.5", "author": "Stefan Goessner", "publisher": "goessner", "keywords": [ @@ -45,6 +45,14 @@ "default": "dollars", "description": "Math formula delimiters." }, + "mdmath.macros": { + "type": "object", + "default": { + "\\RR": "\\mathbb{R}", + "\\vek": "{\\begin{pmatrix}#1\\\\#2\\end{pmatrix}}" + }, + "description": "TeX macros definition." + }, "mdmath.savePath": { "type": "string", "default": "./${file.name}.html", @@ -70,7 +78,7 @@ "category": "Markdown" }, { - "command": "extension.renderToHtml", + "command": "extension.saveToHtml", "title": "Save Markdown+Math to HTML", "category": "Markdown" } @@ -82,7 +90,7 @@ "when": "editorTextFocus" }, { - "command": "extension.renderToHtml", + "command": "extension.saveToHtml", "key": "ctrl+K ,", "when": "editorTextFocus" } @@ -117,16 +125,16 @@ "argparse": "^1.0.9", "clipboardy": "^1.1.2", "cross-spawn": "^6.0.1", - "entities": "^1.1.1", + "entities": "^1.1.2", "execa": "^1.0.0", - "get-stream": "^4.0.0", + "get-stream": "^4.1.0", "is-stream": "^1.1.0", "isexe": "^2.0.0", - "katex": "^0.10.0-rc.1", + "katex": "^0.10.0", "linkify-it": "^2.0.3", "lru-cache": "^4.1.3", "markdown-it": "^8.4.2", - "markdown-it-texmath": "^0.5.2", + "markdown-it-texmath": "^0.5.3", "match-at": "^0.1.0", "mdurl": "^1.0.1", "mkdirp": "^0.5.1", @@ -138,7 +146,7 @@ "shebang-regex": "^2.0.0", "signal-exit": "^3.0.0", "sprintf-js": "^1.1.1", - "strip-eof": "^1.0.0", + "strip-eof": "^2.0.0", "uc.micro": "^1.0.3", "which": "^1.3.1", "yallist": "^3.0.0" diff --git a/readme.md b/readme.md index 0a36ae4..f0533c8 100644 --- a/readme.md +++ b/readme.md @@ -12,6 +12,11 @@ In fact it now reuses the built in markdown viewer. KaTeX works inside as a fast You can install the extension directly from [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=goessner.mdmath). +### What is new in **mdmath** 2.3.5 ... +* 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 setting `mdmath.savePath`. +* Activate `autosave` feature (default: `false`), so whenever you are saving the markdown file, its corresponding HTML file is also saved (to `mdmath.savePath`). Simply set user setting `mdmath.autosave: true` for this. + ## 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 @@ -21,15 +26,12 @@ document format. * Display math * Formula numbering * Inline math with tables -* Export resulting HTML code for web usage - -### What is new in **mdmath** 2.0 ... +* 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](https://github.com/markdown-it/markdown-it) plugin [markdown-it-texmath](https://github.com/goessner/markdown-it-texmath). * Using vscode's [Markdown Extension API](https://code.visualstudio.com/docs/extensionAPI/api-markdown). * Editor view and Preview are synchronized while scrolling. -* Heavily reduced code size. -* Works offline. +* Copy resulting HTML code to the system clipboard. * 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: * `'dollars'` (default) * inline: `$...$` @@ -78,13 +80,18 @@ 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 `Clip Markdown+Math to HTML` to copy the - corresponding HTML source to the underlying systems clipboard. +* 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. ## Default User Settings ```json // Path to custom stylesheet file (css). "mdmath.delimiters": "dollars", + "mdmath.macros": { + "type": "object", + "default": {}, + "description": "TeX macros definition." + }, "mdmath.savePath": "./${file.name}.html", "mdmath.autosave": false ``` @@ -96,15 +103,42 @@ npm install * [`clipboardy`](https://github.com/sindresorhus/clipboardy): Access the system clipboard (copy/paste). ## FAQ +* __How to define and use macros ?__ + * Define them in user settings. For example ... + ```json + "mdmath.macros": { + "type": "object", + "default": { + "\\RR": "\\mathbb{R}", + "\\vek": "{\\begin{pmatrix}#1\\\\#2\\end{pmatrix}}" + }, + "description": "TeX macros definition." + } + ``` + * 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. +* __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 ?__ - * Math formula highlighting is experimental. * 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 Reference](https://khan.github.io/KaTeX/docs/supported.html). + * 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). * __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 ?__ @@ -140,7 +174,8 @@ npm install The following folks helped to make `mdmath` even better. -* [colinfang](https://github.com/colinfang): Implemented global Macros with mdmath 2.3.0. +* [elviswolcott](https://github.com/elviswolcott): Implemented the feature of directly saving HTML to the file system including `autosave` ability. +* [colinfang](https://github.com/colinfang): helped with implementing macros for mdmath 2.3.5. * [lincr](https://github.com/LCAR979): Helped with fixing problems with `mdmath.clipToHtml` under Ubuntu. * [TonySFU](https://github.com/TonySFU): Helped with fixing encoding problems with Chinese language under macOS when using `mdmath.clipToHtml`. * [floatdrop](https://github.com/floatdrop): Verifying that [clipboardy](https://github.com/sindresorhus/clipboardy) is a better alternative to `copy-paste` by implementing. diff --git a/triangle.html b/triangle.html new file mode 100644 index 0000000..655863e --- /dev/null +++ b/triangle.html @@ -0,0 +1,41 @@ + + + + + + + + +

The Right Triangle

+

Base Geometry

+

+

Let the right triangle hypothenuse be aligned with the coordinate system x-axis. +The vector loop closure equation running counter-clockwise then reads

+
aeα+be~α+cex=0a{\bold e}_\alpha + b\tilde{\bold e}_\alpha + c{\bold e}_x = \bold 0(1)

with

+
eα=(cos⁡αsin⁡α)ande~α=(−sin⁡αcos⁡α){\bold e}_\alpha = \begin{pmatrix}\cos\alpha\\ \sin\alpha\end{pmatrix} \quad and \quad {\tilde\bold e}_\alpha = \begin{pmatrix}-\sin\alpha\\ \cos\alpha\end{pmatrix}

Resolving for the hypothenuse part cexc{\bold e}_x in the loop closure equation (1)

+
−cex=aeα+be~α-c{\bold e}_x = a{\bold e}_\alpha + b\tilde{\bold e}_\alpha

and squaring

+
+

finally results in the Pythagorean theorem (2)

+
c2=a2+b2c^2 = a^2 + b^2(2)
+

More Triangle Stuff

+

Introducing the hypothenuse segments p=a⋅exp={\bold a}\cdot{\bold e}_x and q=b⋅exq={\bold b}\cdot{\bold e}_x, we can further obtain the following useful formulas.

+ + + + + + + + + + + + + + + + + +
segment psegment qheight harea
cp=a2cp = a^2cq=b2cq = b^2pq=h2pq = h^2ab=chab = ch
+ + \ No newline at end of file diff --git a/triangle.md b/triangle.md index d70f395..f3d4fe5 100644 --- a/triangle.md +++ b/triangle.md @@ -2,12 +2,12 @@ ## Base Geometry -![at](img/triangle.png) +![](./img/triangle.png) Let the right triangle hypothenuse be aligned with the coordinate system *x-axis*. The vector loop closure equation running counter-clockwise then reads -$$a{\bold e}_\alpha + b\tilde{\bold e}_\alpha + c{\bold e}_x = \bold 0$$ +$$a{\bold e}_\alpha + b\tilde{\bold e}_\alpha + c{\bold e}_x = \bold 0$$ (1) with