New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
mathlifier
Advanced tools
mathlifier - npm Package Compare versions
Comparing version 1.3.5 to 2.0.0
| { | ||
| "name": "mathlifier", | ||
| "version": "1.3.5", | ||
| "description": "A KaTeX renderToString wrapper", | ||
| "source": "src/index.ts", | ||
| "type": "module", | ||
| "main": "dist/index.cjs", | ||
| "module": "dist/index.js", | ||
| "types": "dist/index.d.ts", | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "scripts": { | ||
| "prepare": "tsup", | ||
| "prepublishOnly": "pnpm test && pnpm lint", | ||
| "preversion": "pnpm lint", | ||
| "version": "pnpm format", | ||
| "postversion": "git add . && git commit -m 'new version' && git push --tags", | ||
| "format": "prettier --write \"src/**/*.ts\"", | ||
| "lint": "eslint --ignore-path ../../.gitignore", | ||
| "test": "uvu -r tsm src/__tests__", | ||
| "test:coverage": "c8 --include=src pnpm test", | ||
| "build": "tsup" | ||
| }, | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "git+https://github.com/kelvinsjk/mathlified.git", | ||
| "directory": "packages/mathlifier" | ||
| }, | ||
| "keywords": [ | ||
| "math", | ||
| "maths", | ||
| "mathematics", | ||
| "LaTeX", | ||
| "KaTeX", | ||
| "mathlify", | ||
| "mathlifier", | ||
| "mathlified" | ||
| ], | ||
| "author": "Kelvin Soh", | ||
| "license": "MIT", | ||
| "bugs": { | ||
| "url": "https://github.com/kelvinsjk/mathlified/issues" | ||
| }, | ||
| "homepage": "https://github.com/kelvinsjk/mathlified/blob/fce2b0eb417397719e1fe641912e7c5e59676289/packages/mathlifier/README.md", | ||
| "devDependencies": { | ||
| "@types/katex": "^0.16.7", | ||
| "@typescript-eslint/eslint-plugin": "^6.17.0", | ||
| "@typescript-eslint/parser": "^6.17.0", | ||
| "c8": "^9.0.0", | ||
| "eslint": "^8.56.0", | ||
| "prettier": "^3.1.1", | ||
| "tslib": "^2.6.2", | ||
| "tsm": "^2.3.0", | ||
| "tsup": "^8.0.1", | ||
| "typescript": "^5.3.3", | ||
| "uvu": "^0.5.6" | ||
| }, | ||
| "dependencies": { | ||
| "katex": "^0.16.9" | ||
| } | ||
| "name": "mathlifier", | ||
| "version": "2.0.0", | ||
| "type": "module", | ||
| "main": "./dist/mathlifier.umd.cjs", | ||
| "module": "./dist/mathlifier.js", | ||
| "types": "./dist/mathlifier.d.ts", | ||
| "exports": { | ||
| ".": { | ||
| "types": "./dist/mathlifier.d.ts", | ||
| "import": "./dist/mathlifier.js", | ||
| "require": "./dist/mathlifier.umd.cjs" | ||
| } | ||
| }, | ||
| "scripts": { | ||
| "dev": "vite", | ||
| "build": "tsc && vite build", | ||
| "preview": "vite preview", | ||
| "test": "vitest" | ||
| }, | ||
| "devDependencies": { | ||
| "typescript": "^5.5.3", | ||
| "vite": "^5.4.1", | ||
| "vite-plugin-dts": "^4.0.3", | ||
| "vitest": "^2.0.5" | ||
| }, | ||
| "dependencies": { | ||
| "@djot/djot": "^0.3.1", | ||
| "temml": "^0.10.29" | ||
| } | ||
| } |
239
README.md
| # Mathlifier | ||
| A wrapper for KaTeX `renderToString` for inline and displayed math | ||
| > [!IMPORTANT] Breaking change in v2: we now use Temml instead of KaTeX for | ||
| > rendering | ||
| <!-- new blockquote --> | ||
| > Simpler way to render math | ||
| A collection of tools to help render mathematics in HTML and MathML | ||
| [](https://github.com/kelvinsjk/mathlified/tree/main/packages/mathlifier) | ||
@@ -10,115 +17,195 @@ [](https://github.com/kelvinsjk/mathlified/tree/main/packages/mathlifier) | ||
| ## Why Mathlifier? | ||
| ## Installing Mathlifier | ||
| Using KaTeX with dynamic/reactive mathematical content, or | ||
| with server side rendering, typically mean calling | ||
| `katex.renderToString()` many times. | ||
| ```bash | ||
| npm i mathlifier | ||
| ``` | ||
| Mathlifier repackages these function calls as `math()` and `display()`, along with | ||
| 3 opinions: | ||
| ## Using Mathlifier | ||
| ### Opinion 1: throwOnError: false | ||
| ### A sprinkle of math | ||
| > While KaTeX sets throwOnError to `true` by default, we have opted to set it to false | ||
| If you just need a sprinkle of math within your document, use the following | ||
| functions to get HTML/MathML strings. Subsequently attach the the output to the | ||
| DOM along with your other content. | ||
| We think that this facilitates quicker debugging (especially useful when hot module reloading (HMR) is active). | ||
| ```js | ||
| // import functions | ||
| import { math, display, alignStar } from "mathlifier"; | ||
| // example of using these functions | ||
| const inlineMath = math("ax^2+bx+c=0"); | ||
| const displayedMath = display("x=\\frac{-b\\pm\\sqrt{b^2-4ac}}{2a}"); | ||
| const alignedEnv = alignStar("x &= 2-1 \\\\ &= 1"); | ||
| // also available: | ||
| // - align | ||
| // - gather, gatherStar | ||
| // - equation, eqn, equationStar, eqnStar | ||
| // - alignat, alignatStar | ||
| ``` | ||
| ### Opinion 2: No line break in inline math | ||
| ### Dynamic mathematical content via mathlifier | ||
| > By default, we wrap all inputs with braces to prevent automatic line-breaking. | ||
| When working with dynamically generated mathematical content, we find ourselves | ||
| calling the previous functions over and over. Markdown-like notation is also | ||
| easier to handle vs HTML. Because of the potential ambiguity of Markdown leading | ||
| to bugs, we use [Djot](https://djot.net/) syntax (which is very similar to | ||
| markdown). | ||
| Disable this with an [option](#custom-mathlifier-options) | ||
| Mathlifier provides the `mathlifier` tagged template function, which takes Djot | ||
| markup interspersed with math notation interpolations, and outputs a HTML | ||
| string. | ||
| ### Opinion 3: Displayed math with overflow-x: auto | ||
| ```js | ||
| import { mathlifier } from "mathlifier"; | ||
| const x = "x"; | ||
| const xVal = 2; | ||
| const djotMarkup = mathlifier` | ||
| Interpolation starts _math mode_ so ${x} = ${xVal} | ||
| render "x=2" in math mode. | ||
| > By default, we place displayed math inside a container styled with | ||
| > `overflow-x: auto`. We believe this modification makes the output more | ||
| > mobile-friendly. | ||
| _Display_ and _amsmath environment_ modes start with a $ before interpolation, | ||
| spans multiple lines and ends with an empty line. | ||
| Amsmath environments are automatically closed after they end. | ||
| Disable this with an [option](#custom-mathlifier-options) | ||
| $${xVal}x^2 + x - 3 | ||
| = ${xVal} | ||
| ## Installing Mathlifier | ||
| $${"align"} x &= ${xVal} | ||
| \\\\ y &= 3 | ||
| ```bash | ||
| npm i mathlifier | ||
| If we want to *prevent* math mode and do regular interpolation (ie text), prefix with an @ symbol, like this e@${x}cellent example. | ||
| Regular static math will also be converted. For example, $x=2$ and $$y=3.$$ | ||
| This means that regular dollar signs must be escaped, like \\$5. | ||
| `; | ||
| ``` | ||
| ## Using Mathlifier | ||
| The `mathlifierTex` tagged template function tags math and display environment | ||
| with $ and $$ delimiters. This is useful for producing LaTeX, though take note | ||
| that amsmath environments are placed within $$ delimiters, which is invalid | ||
| LaTeX behavior but necessary for the web. | ||
| The `mathliferDj` tagged template function returns Djot markup, so $x$ and $$y$$ | ||
| become $\`x\` and $$\`y\`. The `mathlifier` function uses `mathlifierTex` and | ||
| `mathlifierDj` under the hood and finally renders the djot markup produced with | ||
| the Djot library, adding an override to produce math output via Temml. | ||
| Finally we also provide the `mathlifierFactory` function to help you design your | ||
| own "mathlifier" function by specifying how math/display math and | ||
| math-environments should be handled. For example, a LaTeX focused | ||
| "`mathlifierLatex`" function can be produced by the following: | ||
| ```js | ||
| // import functions | ||
| import { math, display } from 'mathlifier'; | ||
| // example of using these functions | ||
| const inlineMath = math('ax^2+bx+c=0'); | ||
| const displayedMath = display('x=\\frac{-b\\pm\\sqrt{b^2-4ac}}{2a}'); | ||
| const mathlifierLatex = mathlifierFactory({ | ||
| math: (x) => "\\(" + x + ")\\", | ||
| display: (x) => "\\[" + x + "]\\", | ||
| mathEnvs: { | ||
| equation: (x) => "\\begin{equation}" + x + "\\end{equation}", | ||
| // etc | ||
| }, | ||
| }); | ||
| ``` | ||
| Subsequently, attach the HTML string(s) generated to the DOM. | ||
| ## Temml options | ||
| ### KaTeX Stylesheet | ||
| All [Temml options](https://temml.org/docs/en/administration#options) are passed | ||
| along. | ||
| Just like in KaTeX, we will need to add a stylesheet. Refer to the [KaTeX Documentation](https://katex.org/docs/browser.html) for more details, or add | ||
| the following into the head element. | ||
| ```js | ||
| // example of Temml options | ||
| const noWrap = math("x=1", { wrap: "none" }); | ||
| const leftEqn = display("\\begin{equation} x \\inR \\end{equation}", { | ||
| leqno: true, | ||
| macros: { | ||
| "\\inR": "\\in \\mathbb{R}", | ||
| }, | ||
| }); | ||
| ``` | ||
| ```html | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css" | ||
| integrity="sha384-vKruj+a13U8yHIkAyGgK1J3ArTLzrFGBbBc0tDp4ad/EyewESeXE/Iv67Aj8gKZ0" | ||
| crossorigin="anonymous" | ||
| /> | ||
| ```js | ||
| import { mathlifier, setOptions } from "mathlifier"; | ||
| setOptions({ temmlOptions: { macros: { "\\inR": "\\in \\mathbb{R}" } } }); | ||
| const macrosEnabledMarkup = mathlifier`$ x \\inR $`; | ||
| // the resetOptions function can be used to reset this behavior | ||
| ``` | ||
| ## Custom Mathlifier options | ||
| ## V1 vs V2 | ||
| We can disable the default behavior (opinions 2 and 3 above) of Mathlifier vs regular KaTeX | ||
| Previously existing functions (`math`, `display`, `align`, etc) should work | ||
| similarly. The difference is that they now produce MathML strings via Temml | ||
| instead of KaTeX. See the [Temml GitHub repo](https://github.com/ronkok/Temml) | ||
| for the differences between the two libraries. | ||
| ```js | ||
| // example of Mathlifier options | ||
| const allowBreak = math('e^{i\\pi} = -1', { wrap: true }); | ||
| const noContainer = display('\\sum_{r=1}^n = \\frac{n(n+1)}{2}', { overflowAuto: false }); | ||
| ``` | ||
| ### Functions that are removed | ||
| ## KaTeX options | ||
| The following functions, that were available but not documented, are removed in | ||
| V2. | ||
| All [KaTeX options](https://katex.org/docs/options.html) are passed along. | ||
| - linebreak, newline, newParagraph | ||
| - bold, strong, emph, em | ||
| - html, tex, htmlTex | ||
| ```js | ||
| // example of KaTeX options | ||
| const leftEqn = display('\\begin{equation} A = \\pi r^2 \\end{equation}', { | ||
| leqno: true, | ||
| fleqn: true, | ||
| }); | ||
| ``` | ||
| These functions were used, along with the separate `mathlifier2` library, in an | ||
| attempt to have a single source code output to web and LaTeX. We have since | ||
| achieved this goal by using Djot markup along with the new `mathlifier` tagged | ||
| template function, so they are no longer necessary. | ||
| ## Other features | ||
| ### Upgrading to V2 | ||
| We also have quick wrappers for four of the commonly used display environments: `align`, `align*`, `gather`, `gather*`. | ||
| To upgrade, you can remove the CSS file for KaTeX required in V1 and add the CSS | ||
| and font files for Temml required in V2. See the | ||
| [Temml docs](https://temml.org/docs/en/administration#overview) for information | ||
| for those files. | ||
| ```js | ||
| // display environments | ||
| import { align, alignStar, gather, gatherStar } from 'mathlifier'; | ||
| const gatherEnv = alignStar(` | ||
| x+3y &= 3 \\\\ | ||
| 2x-y &= -2 | ||
| `); | ||
| // equivalent to | ||
| // display(`\\begin{align*} | ||
| // x+3y &= 3 \\\\ | ||
| // 2x-y &= -2 | ||
| // \\end{align*} | ||
| // `); | ||
| ``` | ||
| ### Why we made the switch | ||
| ### Typesetting Utils | ||
| Temml is more lightweight than KaTeX and MathJax. Moreover, one common pain | ||
| point in the previous use of KaTeX was double rendering if we did not include | ||
| the css file. With Temml able to use local fonts, we found that the output still | ||
| looks passable for simple use cases if one was to miss out on the css and font | ||
| file (we do still highly recommend adding them to your project for the best | ||
| rendering output) | ||
| We have also added `linebreak` (to add the html `<br>` tag) and the function `bold(x)` | ||
| (to wrap `x` in the `<strong></strong>` environment). | ||
| ### Update on previous opinions | ||
| This is to facilitate using the same javascript code to generate both HTML (via KaTeX) | ||
| and LaTeX by swapping out this library for an upcoming package (Mathlifier2?). | ||
| Mathlifier imposed 3 default opinions on the output in V1. | ||
| #### Opinion 1: throwOnError: false | ||
| Unlike KaTeX, Temml sets this to false by default so there is **no change** in | ||
| V2. | ||
| #### Opinion 2: No line break in inline math | ||
| **Breaking change**. We have since come around on this opinion (this ensures | ||
| compatibility if writing source code meant for both the web and LaTeX). | ||
| You can maintain previous behavior by wrapping your input with braces: | ||
| `math("{x=a=2}")`. Temml also ships with a `wrap` option so we can use | ||
| `math("x=a=2", {wrap: "none"})` to prevent line breaking. | ||
| By default, Temml sets a soft line break after every top-level relation and | ||
| binary operator, like in TeX. They also supply an `=` option for a soft line | ||
| break before the second and subsequent top-level `=` signs, which we can use | ||
| `math("x=a=2", {wrap: "="})`. | ||
| #### Opinion 3: Displayed math with overflow-x: auto | ||
| **Breaking change**. We still believe in this opinion as it makes our output | ||
| more mobile-friendly. However, our original approach of using an inline-style | ||
| makes it hard for the css Cascade to override for power users. | ||
| We recommend adding the following css rule to replicate the previous behavior. | ||
| ```css | ||
| *:has(> math.tml-display) { | ||
| overflow-x: auto; | ||
| width: 100%; | ||
| } | ||
| ``` | ||
| ## Credits | ||
| [KaTeX](https://katex.org/) | ||
| - [Temml](https://temml.org) | ||
| - [Djot](https://djot.net) | ||
@@ -125,0 +212,0 @@ ## License |
New alerts
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
No contributors or author data
MaintenancePackage does not specify a list of contributors or an author in package.json.
Found 1 instance in 1 package
No bug tracker
MaintenancePackage does not have a linked bug tracker in package.json.
Found 1 instance in 1 package
No License Found
License(Experimental) License information could not be found.
Found 1 instance in 1 package
No repository
Supply chain riskPackage does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.
Found 1 instance in 1 package
No website
QualityPackage does not have a website.
Found 1 instance in 1 package
Improved metrics
- Dev dependency count
4
-63.64%- Number of package files
22
175%- Lines of code
714
14.24%- Number of lines in readme file
214
68.5%Worsened metrics
- Total package byte prevSize
37096
-52.83%- Dependency count
2
100%- Number of low license alerts
1
Infinity%- Number of low maintenance alerts
2
Infinity%- Number of low quality alerts
1
Infinity%- Number of low supply chain risk alerts
1
Infinity%- Number of medium supply chain risk alerts
1
Infinity%Dependency changes
+ Added
@djot/djot@^0.3.1+ Added
temml@^0.10.29+ Added
@djot/djot@0.3.2(transitive)+ Added
temml@0.10.34(transitive)- Removed
katex@^0.16.9- Removed
commander@8.3.0(transitive)- Removed
katex@0.16.21(transitive)