Brunobkr/llama.cpp_AlgMor24_github

1# micromark-extension-math2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7[![Sponsors][sponsors-badge]][collective]8[![Backers][backers-badge]][collective]9[![Chat][chat-badge]][chat]10 11[micromark][] extensions to support math (`$C_L$`).12 13## Contents14 15* [What is this?](#what-is-this)16* [When to use this](#when-to-use-this)17* [Install](#install)18* [Use](#use)19* [API](#api)20  * [`math(options?)`](#mathoptions)21  * [`mathHtml(options?)`](#mathhtmloptions)22  * [`HtmlOptions`](#htmloptions)23  * [`Options`](#options)24* [Authoring](#authoring)25* [HTML](#html)26* [CSS](#css)27* [Syntax](#syntax)28* [Types](#types)29* [Compatibility](#compatibility)30* [Security](#security)31* [Related](#related)32* [Contribute](#contribute)33* [License](#license)34 35## What is this?36 37This package contains two extensions that add support for math syntax38in markdown to [`micromark`][micromark].39 40As there is no spec for math in markdown, this extension follows how code41(fenced and text) works in Commonmark, but uses dollars.42 43## When to use this44 45This project is useful when you want to support math in markdown.46Extending markdown with a syntax extension makes the markdown less portable.47LaTeX equations are also quite hard.48But this mechanism works well when you want authors, that have some LaTeX49experience, to be able to embed rich diagrams of math in scientific text.50 51You can use these extensions when you are working with [`micromark`][micromark]52already.53 54When you need a syntax tree, you can combine this package with55[`mdast-util-math`][mdast-util-math].56 57All these packages are used [`remark-math`][remark-math], which focusses on58making it easier to transform content by abstracting these internals away.59 60## Install61 62This package is [ESM only][esm].63In Node.js (version 16+), install with [npm][]:64 65[npm][]:66 67```sh68npm install micromark-extension-math69```70 71In Deno with [`esm.sh`][esmsh]:72 73```js74import {math, mathHtml} from 'https://esm.sh/micromark-extension-math@3'75```76 77In browsers with [`esm.sh`][esmsh]:78 79```html80<script type="module">81  import {math, mathHtml} from 'https://esm.sh/micromark-extension-math@3?bundle'82</script>83```84 85## Use86 87Say our document `example.md` contains:88 89```markdown90Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following equation.91 92$$93L = \frac{1}{2} \rho v^2 S C_L94$$95```96 97…and our module `example.js` looks as follows:98 99```js100import fs from 'node:fs/promises'101import {micromark} from 'micromark'102import {math, mathHtml} from 'micromark-extension-math'103 104const output = micromark(await fs.readFile('example.md'), {105  extensions: [math()],106  htmlExtensions: [mathHtml()]107})108 109console.log(output)110```111 112…now running `node example.js` yields (abbreviated):113 114```html115<p>Lift(<span class="math math-inline"><span class="katex">…</span></span>) can be determined by Lift Coefficient (<span class="math math-inline"><span class="katex">…</span></span>) like the following equation.</p>116<div class="math math-display"><span class="katex-display"><span class="katex">…</span></span></div>117```118 119## API120 121This package exports the identifiers [`math`][api-math] and122[`mathHtml`][api-math-html].123There is no default export.124 125The export map supports the [`development` condition][development].126Run `node --conditions development module.js` to get instrumented dev code.127Without this condition, production code is loaded.128 129### `math(options?)`130 131Create an extension for `micromark` to enable math syntax.132 133###### Parameters134 135* `options` ([`Options`][api-options], default: `{}`)136  — configuration137 138###### Returns139 140Extension for `micromark` that can be passed in `extensions`, to enable math141syntax ([`Extension`][micromark-extension]).142 143### `mathHtml(options?)`144 145Create an extension for `micromark` to support math when serializing to HTML.146 147> 👉 **Note**: this uses KaTeX to render math.148 149###### Parameters150 151* `options` ([`HtmlOptions`][api-html-options], default: `{}`)152  — configuration153 154###### Returns155 156Extension for `micromark` that can be passed in `htmlExtensions`, to support157math when serializing to HTML ([`HtmlExtension`][micromark-html-extension]).158 159### `HtmlOptions`160 161Configuration for HTML output (optional).162 163> 👉 **Note**: passed to [`katex.renderToString`][katex-options].164> `displayMode` is overwritten by this plugin, to `false` for math in text165> (inline), and `true` for math in flow (block).166 167###### Type168 169```ts170type Options = Omit<import('katex').KatexOptions, 'displayMode'>171```172 173### `Options`174 175Configuration (TypeScript type).176 177###### Fields178 179* `singleDollarTextMath` (`boolean`, default: `true`)180  — whether to support math (text, inline) with a single dollar.181  Single dollars work in Pandoc and many other places, but often interfere182  with “normal” dollars in text.183  If you turn this off, you use two or more dollars for text math.184 185## Authoring186 187When authoring markdown with math, keep in mind that math doesn’t work in most188places.189Notably, GitHub currently has a really weird crappy client-side regex-based190thing.191But on your own (math-heavy?) site it can be great!192You can use code (fenced) with an info string of `math` to improve this, as193that works in many places.194 195## HTML196 197Math (flow) does not relate to HTML elements.198`MathML`, which is sort of like SVG but for math, exists but it doesn’t work199well and isn’t widely supported.200Instead, this uses [KaTeX][], which generates MathML as a fallback but also201generates a bunch of divs and spans so math look pretty.202The KaTeX result is wrapped in `<div>` (for flow, block) and `<span>` (for text,203inline) elements, with two classes: `math` and either `math-display` or204`math-inline`.205 206When turning markdown into HTML, each line ending in math (text) is turned207into a space.208 209## CSS210 211The HTML produced by KaTeX requires CSS to render correctly.212You should use `katex.css` somewhere on the page where the math is shown to213style it properly.214At the time of writing, the last version is:215 216<!-- To do: update and copy paste the one from: https://katex.org/docs/browser -->217 218```html219<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">220```221 222## Syntax223 224Math forms with the following BNF:225 226```bnf227; Restriction: the number of markers in the closing sequence must be equal228; to the number of markers in the opening sequence.229math_text ::= sequence_text 1*byte sequence_text230math_flow ::= fence_open *( eol *line ) [ eol fence_close ]231 232; Restriction: not preceded or followed by the marker.233sequence_text ::= 1*'$'234 235fence_open ::= sequence_flow meta236; Restriction: the number of markers in the closing fence sequence must be237; equal to or greater than the number of markers in the opening fence238; sequence.239fence_close ::= sequence_flow *space_or_tab240sequence_flow ::= 2*'$'241; Restriction: the marker cannot occur in `meta`242meta ::= 1*line243 244; Character groups for informational purposes.245byte ::= 0x00..=0xFFFF246eol ::= '\n' | '\r' | '\r\n'247line ::= byte - eol248```249 250The above grammar shows that it is not possible to create empty math (text).251It is possible to include the sequence marker (dollar) in math (text), by252wrapping it in bigger or smaller sequences:253 254```markdown255Include more: $a$$b$ or include less: $$a$b$$.256```257 258It is also possible to include just one marker:259 260```markdown261Include just one: $$ $ $$.262```263 264Sequences are “gready”, in that they cannot be preceded or followed by more265markers.266To illustrate:267 268```markdown269Not math: $$x$.270 271Not math: $x$$.272 273Escapes work, this is math: \$$x$.274 275Escapes work, this is math: $x$\$.276```277 278Yields:279 280```html281<p>Not math: $$x$.</p>282<p>Not math: $x$$.</p>283<p>Escapes work, this is math: $<span>…</span>.</p>284<p>Escapes work, this is math: <span>…</span>$.</p>285```286 287That is because, when turning markdown into HTML, the first and last space,288if both exist and there is also a non-space in the math, are removed.289Line endings, at that stage, are considered as spaces.290 291As the math (flow) construct occurs in flow, like all flow constructs, it must292be followed by an eol (line ending) or eof (end of file).293 294The above grammar does not show how indentation of each line is handled.295To parse math (flow), let `x` be the number of `space_or_tab` characters296before the opening fence sequence, after interpreting tabs based on how many297virtual spaces they represent.298Each line of text is then allowed (not required) to be indented with up299to `x` spaces or tabs, which are then ignored as an indent instead of being300considered as part of the content.301This indent does not affect the closing fence.302It can be indented up to a separate 3 real or virtual spaces.303A bigger indent makes it part of the content instead of a fence.304 305The `meta` part is interpreted as the [string][micromark-content-types] content306type.307That means that character escapes and character references are allowed.308 309The optional `meta` part is ignored: it is not used when parsing or310rendering.311 312## Types313 314This package is fully typed with [TypeScript][].315It exports the additional types [`HtmlOptions`][api-html-options]316and [`Options`][api-options].317 318## Compatibility319 320Projects maintained by the unified collective are compatible with maintained321versions of Node.js.322 323When we cut a new major release, we drop support for unmaintained versions of324Node.325This means we try to keep the current release line,326`micromark-extension-math@^3`, compatible with Node.js 16.327 328This package works with `micromark` version `3` and later.329 330## Security331 332This package is safe assuming that you trust KaTeX.333Any vulnerability in it could open you to a [cross-site scripting (XSS)][xss]334attack.335 336## Related337 338* [`remark-math`][remark-math]339  — remark (and rehype) plugins to support math340* [`mdast-util-math`][mdast-util-math]341  — mdast utility to support math342 343## Contribute344 345See [`contributing.md` in `micromark/.github`][contributing] for ways to get346started.347See [`support.md`][support] for ways to get help.348 349This project has a [code of conduct][coc].350By interacting with this repository, organization, or community you agree to351abide by its terms.352 353## License354 355[MIT][license] © [Titus Wormer][author]356 357<!-- Definitions -->358 359[build-badge]: https://github.com/micromark/micromark-extension-math/workflows/main/badge.svg360 361[build]: https://github.com/micromark/micromark-extension-math/actions362 363[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-math.svg364 365[coverage]: https://codecov.io/github/micromark/micromark-extension-math366 367[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-math.svg368 369[downloads]: https://www.npmjs.com/package/micromark-extension-math370 371[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=micromark-extension-math372 373[size]: https://bundlejs.com/?q=micromark-extension-math374 375[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg376 377[backers-badge]: https://opencollective.com/unified/backers/badge.svg378 379[collective]: https://opencollective.com/unified380 381[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg382 383[chat]: https://github.com/micromark/micromark/discussions384 385[npm]: https://docs.npmjs.com/cli/install386 387[esmsh]: https://esm.sh388 389[license]: license390 391[author]: https://wooorm.com392 393[contributing]: https://github.com/micromark/.github/blob/main/contributing.md394 395[support]: https://github.com/micromark/.github/blob/main/support.md396 397[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md398 399[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c400 401[typescript]: https://www.typescriptlang.org402 403[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions404 405[micromark]: https://github.com/micromark/micromark406 407[micromark-content-types]: https://github.com/micromark/micromark#content-types408 409[micromark-html-extension]: https://github.com/micromark/micromark#htmlextension410 411[micromark-extension]: https://github.com/micromark/micromark#syntaxextension412 413[mdast-util-math]: https://github.com/syntax-tree/mdast-util-math414 415[remark-math]: https://github.com/remarkjs/remark-math416 417[katex]: https://katex.org418 419[katex-options]: https://katex.org/docs/options.html420 421[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting422 423[api-math]: #mathoptions424 425[api-math-html]: #mathhtmloptions426 427[api-options]: #options428 429[api-html-options]: #htmloptions430