https://github.com/lucpotage/vue-katex

Vue plugin for KaTeX
https://github.com/lucpotage/vue-katex

katex vue

Last synced: 14 days ago
JSON representation

Vue plugin for KaTeX

• Host: GitHub
• URL: https://github.com/lucpotage/vue-katex
• Owner: lucpotage
• License: mit
• Created: 2017-12-06T12:27:04.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2023-11-04T07:48:23.000Z (about 1 year ago)
• Last Synced: 2024-10-22T11:12:25.772Z (22 days ago)
• Topics: katex, vue
• Language: JavaScript
• Size: 1.97 MB
• Stars: 128
• Watchers: 7
• Forks: 22
• Open Issues: 24
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# vue-katex

KaTeX enables fast math typesetting for the web. **vue-katex** is a lightweight plugin introduces a simple way to use [KaTeX](https://github.com/KaTeX/KaTeX) in your Vue app. Enjoy! 🙂

[![NPM version](https://img.shields.io/npm/v/vue-katex.svg?style=flat)](https://www.npmjs.com/package/vue-katex) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Build Status](https://travis-ci.org/lucpotage/vue-katex.svg?branch=master)](https://travis-ci.org/lucpotage/vue-katex)

[![codecov](https://codecov.io/gh/lucpotage/vue-katex/branch/master/graph/badge.svg)](https://codecov.io/gh/lucpotage/vue-katex)

# Installation

Install `vue-katex` with `katex` as a peer dependency

```

# With NPM

npm i vue-katex katex -P

# With Yarn

yarn add vue-katex katex

```

As explained in the [KaTeX documentation](https://katex.org/docs/node.html), you must also add the related stylesheet.

```html

  @import "../node_modules/katex/dist/katex.min.css";

```

or 

```js

import 'katex/dist/katex.min.css';

```

# Getting started

In your script entry point:

```js

import Vue from 'vue';

import VueKatex from 'vue-katex';

import 'katex/dist/katex.min.css';

Vue.use(VueKatex, {

  globalOptions: {

    //... Define globally applied KaTeX options here

  }

});

```

Now you are all setup to use the plugin.

# Usage

There are two ways to use vue-katex, using the `KatexElement` component or using the `v-katex` directive.  

### Global Options

Options applied globally through the plugin will be merged with any options applied locally to the `v-katex` directive or `KatexElement`. Locally applied options have a higher precedence and will override globally applied options, the exception to this is any KaTeX option of the type `object` or `array`. These will be merged with the resultant option containing all global and local keys or elements.

### Using the katex directive

In your template (don't forget to escape all backslashes):

```html



```


To render the math in display mode:

```html



```


To add KaTeX options, use an object literal instead:

```html



```


### Using the katex directive with auto-render

```html



  \(\frac{a_i}{1+x}\)



```


Options can be applied as follows

```html



  \(\frac{a_i}{1+x}\)



```


See KaTeX documentation for [auto-render](https://katex.org/docs/autorender.html) for more information.

### Using the KatexElement component

```html

```

Through props `KatexElement` supports all of the same options that KaTeX supports.

| Props |

| :----- |

|


`expression`
 
**Type:** `String` **Required**
 A TeX expression to be displayed.
|

|


`display-mode`
 
**Type:** `Boolean` **Default:** `false`
 If true the math will be rendered in display mode, which will put the math in display style (so `\int` and `\sum` are large, for example), and will center the math on the page on its own line. If false the math will be rendered in inline mode.
|

|


`throw-on-error`

**Type:** `Boolean` **Default:** `false`
 If true, KaTeX will throw a `ParseError` when it encounters an unsupported command or invalid LaTeX. If false, KaTeX will render unsupported commands as text, and render invalid LaTeX as its source code with hover text giving the error, in the color given by `errorColor`.
|

|
 
`error-color="#CC0000"`
 
**Type:** `String` **Default:** `#CC0000` 
 A color string given in the format "#XXX" or "#XXXXXX". This option determines the color that unsupported commands and invalid LaTeX are rendered in when throwOnError is set to false.
|

|


`macros`

**Type:** `Object` **Default:** `null`
 A collection of custom macros. Each macro is a property with a name like `\name` (written `"\\name"` in JavaScript) which maps to a string that describes the expansion of the macro, or a function that accepts an instance of `MacroExpander` as first argument and returns the expansion as a string. `MacroExpander` is an internal API and subject to non-backwards compatible changes. See [src/macros.js](https://github.com/KaTeX/KaTeX/blob/master/src/macros.js) for its usage. Single-character keys can also be included in which case the character will be redefined as the given macro (similar to TeX active characters). This object will be modified if the LaTeX code defines its own macros via `\gdef`, which enables consecutive calls to KaTeX to share state.
|

|


`color-is-text-color`

**Type:** `Boolean` **Default:** `false`
 If true, `\color` will work like LaTeX's `\textcolor`, and take two arguments (e.g., `\color{blue}{hello}`), which restores the old behavior of KaTeX (pre-0.8.0). If false, `\color` will work like LaTeX's `\color`, and take one argument (e.g., `\color{blue}hello`). In both cases, `\textcolor` works as in LaTeX (e.g., `\textcolor{blue}{hello}`).
|

|


`max-size="Infinity"`

**Type:** `Number` **Default:** `Infinity`
 All user-specified sizes, e.g. in `\rule{500em}{500em}`, will be capped to `maxSize` ems. If set to `Infinity` (the default), users can make elements and spaces arbitrarily large.
|

|


`max-expand="1000"`

**Type:** `Number` **Default:** `1000`
 Limit the number of macro expansions to the specified number, to prevent e.g. infinite macro loops. If set to `Infinity`, the macro expander will try to fully expand as in LaTeX.
|

|


`allowed-protocols="[]"`

**Type:** `String[]` **Default:**  `["http", "https", "mailto", "_relative"]`
 Allowed protocols in `\href`. Use `_relative` to allow relative urls, and `*` to allow all protocols.
|

|


`strict`

**Type:** `[Boolean, String, Function]` **Default:**  `"warn"`
 If `false` or `"ignore"`, allow features that make writing LaTeX convenient but are not actually supported by (Xe)LaTeX (similar to MathJax). If `true` or `"error"` (LaTeX faithfulness mode), throw an error for any such transgressions. If `"warn"` (the default), warn about such behavior via `console.warn`. Provide a custom function `handler(errorCode, errorMsg, token)` to customize behavior depending on the type of transgression (summarized by the string code `errorCode` and detailed in `errorMsg`); this function can also return `"ignore"`, `"error"`, or `"warn"` to use a built-in behavior. A list of such features and their `errorCode`: 


`"unknownSymbol"`: Use of unknown Unicode symbol, which will likely also lead to warnings about missing character metrics, and layouts may be incorrect (especially in terms of vertical heights).

`"unicodeTextInMathMode"`: Use of Unicode text characters in math mode.

`"mathVsTextUnits"`: Mismatch of math vs. text commands and units/mode.

`"commentAtEnd"`: Use of % comment without a terminating newline. LaTeX would thereby comment out the end of math mode (e.g. $), causing an error. A second category of errorCodes never throw errors, but their strictness affects the behavior of KaTeX

`"newLineInDisplayMode"`: Use of \\ or \newline in display mode (outside an array/tabular environment). In strict mode, no line break results, as in LaTeX.





See also: [KaTeX Documentation](https://katex.org/docs/options.html)

# License

vue-katex is released under the [MIT license](http://opensource.org/licenses/MIT).