Brunobkr/llama.cpp_AlgMor24_github

1# rehype-highlight2 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**[rehype][]** plugin to apply syntax highlighting to code with12[`lowlight`][lowlight].13 14## Contents15 16* [What is this?](#what-is-this)17* [When should I use this?](#when-should-i-use-this)18* [Install](#install)19* [Use](#use)20* [API](#api)21  * [`unified().use(rehypeHighlight[, options])`](#unifieduserehypehighlight-options)22  * [`Options`](#options)23* [Example](#example)24  * [Example: ignoring](#example-ignoring)25  * [Example: registering](#example-registering)26  * [Example: aliases](#example-aliases)27  * [Example: sanitation](#example-sanitation)28  * [Example: line numbering and highlighting](#example-line-numbering-and-highlighting)29* [Types](#types)30* [HTML](#html)31* [CSS](#css)32* [Compatibility](#compatibility)33* [Security](#security)34* [Related](#related)35* [Contribute](#contribute)36* [License](#license)37 38## What is this?39 40This package is a [unified][] ([rehype][]) plugin to perform syntax41highlighting.42It uses `highlight.js` through `lowlight`, which is pretty fast, relatively43small, and quite good.44This package bundles 37 [common languages][lowlight-common] by default and you45can register more (190 with [`all`][lowlight-all]).46 47It looks for `<code>` elements (when directly in `<pre>` elements) and changes48them.49You can specify the code language (such as Python) with a `language-*` or50`lang-*` class, where the `*` can be for example `js` (so `language-js`), `md`,51`css`, etc.52By default, code without such a language class is not highlighted.53Pass `detect: true` to detect their programming language and highlight the code54anyway.55You can prevent specific blocks from being highlighted with a `no-highlight` or56`nohighlight` class on the `<code>`.57 58**unified** is a project that transforms content with abstract syntax trees59(ASTs).60**rehype** adds support for HTML to unified.61**hast** is the HTML AST that rehype uses.62This is a rehype plugin that applies syntax highlighting to the AST.63 64## When should I use this?65 66This project is useful when you want to perform syntax highlighting in rehype.67One reason to do that is that it typically means the highlighting happens once68at build time instead of every time at run time.69 70When you want a high quality highlighter that can support tons of grammars and71approaches how GitHub renders code,72you can use [`rehype-starry-night`][rehype-starry-night].73 74This plugin is built on [`lowlight`][lowlight], which is a virtual version of75highlight.js.76You can make a plugin based on this one with lowlight when you want to do things77differently.78 79## Install80 81This package is [ESM only][esm].82In Node.js (version 16+), install with [npm][]:83 84```sh85npm install rehype-highlight86```87 88In Deno with [`esm.sh`][esmsh]:89 90```js91import rehypeHighlight from 'https://esm.sh/rehype-highlight@6'92```93 94In browsers with [`esm.sh`][esmsh]:95 96```html97<script type="module">98  import rehypeHighlight from 'https://esm.sh/rehype-highlight@6?bundle'99</script>100```101 102## Use103 104Say we have the following file `example.html`:105 106```html107<h1>Hello World!</h1>108 109<pre><code class="language-js">var name = "World";110console.warn("Hello, " + name + "!")</code></pre>111```112 113…and our module `example.js` contains:114 115```js116import rehypeHighlight from 'rehype-highlight'117import rehypeParse from 'rehype-parse'118import rehypeStringify from 'rehype-stringify'119import {read} from 'to-vfile'120import {unified} from 'unified'121 122const file = await read('example.html')123 124await unified()125  .use(rehypeParse, {fragment: true})126  .use(rehypeHighlight)127  .use(rehypeStringify)128  .process(file)129 130console.log(String(file))131```132 133…then running `node example.js` yields:134 135```html136<h1>Hello World!</h1>137 138<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> name = <span class="hljs-string">"World"</span>;139<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">warn</span>(<span class="hljs-string">"Hello, "</span> + name + <span class="hljs-string">"!"</span>)</code></pre>140```141 142## API143 144This package exports no identifiers.145The default export is [`rehypeHighlight`][api-rehype-highlight].146 147### `unified().use(rehypeHighlight[, options])`148 149Apply syntax highlighting.150 151###### Parameters152 153* `options` ([`Options`][api-options], optional)154  — configuration155 156###### Returns157 158Transform ([`Transformer`][unified-transformer]).159 160### `Options`161 162Configuration (TypeScript type).163 164###### Fields165 166* `aliases` (`Record<string, Array<string> | string>`, optional)167  — register more aliases;168  passed to [`lowlight.registerAlias`][lowlight-register-alias]169* `detect` (`boolean`, default: `false`)170  — highlight code without language classes by guessing its programming171  language172* `languages` (`Record<string, LanguageFn>`, default:173  [`common`][lowlight-common])174  — register languages; passed to [`lowlight.register`][lowlight-register]175* `plainText` (`Array<string>`, optional)176  — list of language names to not highlight;177  note you can also add `no-highlight` classes178* `prefix` (`string`, default: `'hljs-'`)179  — class prefix180* `subset` (`Array<string>`, default: default: [all][lowlight-all] registered181  languages)182  — names of languages to check when detecting183 184## Example185 186### Example: ignoring187 188There are three ways to not apply syntax highlighting to code blocks.189They can be ignored with an explicit class of `no-highlight` (or `nohighlight`),190an explicit language name that’s listed in `options.plainText`, or by setting191`options.detect` to `false` (default), which prevents `<code>` without a class192from being automatically detected.193 194For example, with `example.html`:195 196```html197<pre><code>this won’t be highlighted due to `detect: false` (default)</code></pre>198 199<pre><code class="no-highlight">this won’t be highlighted due to its class</code></pre>200 201<pre><code class="language-txt">this won’t be highlighted due to `plainText: ['txt']`</code></pre>202```203 204…and `example.js`:205 206```js207import {rehype} from 'rehype'208import rehypeHighlight from 'rehype-highlight'209import {read} from 'to-vfile'210 211const file = await rehype()212  .data('settings', {fragment: true})213  .use(rehypeHighlight, {plainText: ['txt', 'text']})214  .process(await read('example.html'))215 216console.log(String(file))217```218 219…then running that yields the same as `example.html`: none of them are220highlighted.221 222### Example: registering223 224`rehype-highlight` supports 37 commonly used languages by default.225This makes it small to load in browsers and Node.js, while supporting enough226default cases.227You can add more languages.228 229For example, with `example.html`:230 231```html232<pre><code class="language-bnf">a ::= 'a' | 'A'</code></pre>233```234 235…and `example.js`:236 237```js238import bnf from 'highlight.js/lib/languages/bnf'239import {common} from 'lowlight'240import {rehype} from 'rehype'241import rehypeHighlight from 'rehype-highlight'242import {read} from 'to-vfile'243 244const file = await rehype()245  .data('settings', {fragment: true})246  .use(rehypeHighlight, {languages: {...common, bnf}})247  .process(await read('example.html'))248 249console.log(String(file))250```251 252…then running that yields:253 254```html255<pre><code class="hljs language-bnf">a ::= <span class="hljs-string">'a'</span> | <span class="hljs-string">'A'</span></code></pre>256```257 258### Example: aliases259 260You can map your own language flags to `highlight.js` languages.261 262For example, with `example.html`:263 264```html265<pre><code class="language-custom-script">console.log(1)</code></pre>266```267 268…and `example.js`:269 270```js271import {rehype} from 'rehype'272import rehypeHighlight from 'rehype-highlight'273import {read} from 'to-vfile'274 275const file = await rehype()276  .data('settings', {fragment: true})277  // 👉 **Note**: the keys are language names, values are the aliases that you278  // want to also allow as `x` in `language-x` classes.279  .use(rehypeHighlight, {aliases: {'javascript': 'custom-script'}})280  .process(await read('example.html'))281 282console.log(String(file))283```284 285…then running that yields:286 287```html288<pre><code class="hljs language-custom-script"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-number">1</span>)</code></pre>289```290 291### Example: sanitation292 293Applying syntax highlighting in rehype operates on `<code>` elements with294certain classes and it injects many `<span>` elements with classes.295Allowing arbitrary classes is an opening for security vulnerabilities.296 297To make HTML safe in rehype, use [`rehype-sanitize`][rehype-sanitize].298It specifically allows `/^language-./` class names on `<code>` elements.299Which we also use.300So you can use `rehype-highlight` after `rehype-sanitize`:301 302```js303import {unified} from 'unified'304import rehypeHighlight from './index.js'305import rehypeParse from 'rehype-parse'306import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'307import rehypeStringify from 'rehype-stringify'308 309const file = await unified()310  .use(rehypeParse, {fragment: true})311  .use(rehypeSanitize)312  .use(rehypeHighlight)313  .use(rehypeStringify)314  .process('<pre><code className="language-js">console.log(1)</code></pre>')315 316console.log(String(file))317```318 319…yields:320 321```html322<pre><code class="hljs language-js"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-number">1</span>)</code></pre>323```324 325Using plugins *after* `rehype-sanitize`, like we just did, is *safe* assuming326you trust those plugins.327If you do not trust `rehype-highlight`, you can use it before.328But then you need to configure `rehype-sanitize` to keep the classes you allow:329 330```js331import {unified} from 'unified'332import rehypeHighlight from './index.js'333import rehypeParse from 'rehype-parse'334import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'335import rehypeStringify from 'rehype-stringify'336 337const file = await unified()338  .use(rehypeParse, {fragment: true})339  .use(rehypeHighlight)340  .use(rehypeSanitize, {341    ...defaultSchema,342    attributes: {343      ...defaultSchema.attributes,344      span: [345        ...(defaultSchema.attributes?.span || []),346        // Allow all class names starting with `hljs-`.347        ['className', /^hljs-./]348        // Alternatively, to allow only certain class names:349        // ['className', 'hljs-number', 'hljs-title', 'hljs-variable']350      ]351    },352    tagNames: [...(defaultSchema.tagNames || []), 'span']353  })354  .use(rehypeStringify)355  .process('<pre><code className="language-js">console.log(1)</code></pre>')356 357console.log(String(file))358```359 360### Example: line numbering and highlighting361 362You can add support for line numbers and line highlighting with a separate363plugin, [`rehype-highlight-code-lines`][rehype-highlight-code-lines].364 365For example, with `example.html`:366 367```html368<pre><code class="language-js">console.log("Hi!")</code></pre>369```370 371…and `example.js`:372 373```js374import {rehype} from 'rehype'375import rehypeHighlight from 'rehype-highlight'376import rehypeHighlightCodeLines from 'rehype-highlight-code-lines'377import {read} from 'to-vfile'378 379const file = await rehype()380  .data('settings', {fragment: true})381  .use(rehypeHighlight)382  .use(rehypeHighlightCodeLines, {383    showLineNumbers: true,384    lineContainerTagName: 'div'385  })386  .process(await read('example.html'))387 388console.log(String(file))389```390 391…then running that yields:392 393```html394<pre><code class="hljs language-js"><div class="code-line numbered-code-line" data-line-number="1"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">"Hi!"</span>)</div></code></pre>395```396 397## Types398 399This package is fully typed with [TypeScript][].400It exports the additional type [`Options`][api-options].401 402## HTML403 404On the input side,405this plugin looks for code blocks with a `language-*` class.406 407On the output side,408this plugin generates `span` elements with classes that can be enhanced with409CSS.410 411## CSS412 413See [“CSS” in `lowlight`][github-lowlight-css] for more info.414 415## Compatibility416 417Projects maintained by the unified collective are compatible with maintained418versions of Node.js.419 420When we cut a new major release, we drop support for unmaintained versions of421Node.422This means we try to keep the current release line, `rehype-highlight@^7`,423compatible with Node.js 16.424 425This plugin works with `rehype-parse` version 1+, `rehype-stringify` version 1+,426`rehype` version 1+, and `unified` version 4+.427 428## Security429 430Use of `rehype-highlight` *should* be safe to use as `highlight.js` and431`lowlight` *should* be safe to use.432When in doubt, use [`rehype-sanitize`][rehype-sanitize].433 434## Related435 436* [`rehype-starry-night`][rehype-starry-night]437  — apply syntax highlighting with `starry-night`438* [`rehype-meta`](https://github.com/rehypejs/rehype-meta)439  — add metadata to the head of a document440* [`rehype-document`](https://github.com/rehypejs/rehype-document)441  — wrap a fragment in a document442* [`rehype-highlight-code-lines`][rehype-highlight-code-lines]443  — add line numbers and highlight lines444 445## Contribute446 447See [`contributing.md`][contributing] in [`rehypejs/.github`][health] for ways448to get started.449See [`support.md`][support] for ways to get help.450 451This project has a [code of conduct][coc].452By interacting with this repository, organization, or community you agree to453abide by its terms.454 455## License456 457[MIT][license] © [Titus Wormer][author]458 459<!-- Definitions -->460 461[api-options]: #options462 463[api-rehype-highlight]: #unifieduserehypehighlight-options464 465[author]: https://wooorm.com466 467[backers-badge]: https://opencollective.com/unified/backers/badge.svg468 469[build]: https://github.com/rehypejs/rehype-highlight/actions470 471[build-badge]: https://github.com/rehypejs/rehype-highlight/workflows/main/badge.svg472 473[chat]: https://github.com/rehypejs/rehype/discussions474 475[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg476 477[coc]: https://github.com/rehypejs/.github/blob/HEAD/code-of-conduct.md478 479[collective]: https://opencollective.com/unified480 481[contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md482 483[coverage]: https://codecov.io/github/rehypejs/rehype-highlight484 485[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype-highlight.svg486 487[downloads]: https://www.npmjs.com/package/rehype-highlight488 489[downloads-badge]: https://img.shields.io/npm/dm/rehype-highlight.svg490 491[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c492 493[esmsh]: https://esm.sh494 495[github-lowlight-css]: https://github.com/wooorm/lowlight#css496 497[health]: https://github.com/rehypejs/.github498 499[license]: license500 501[lowlight]: https://github.com/wooorm/lowlight502 503[lowlight-all]: https://github.com/wooorm/lowlight#all504 505[lowlight-common]: https://github.com/wooorm/lowlight#common506 507[lowlight-register]: https://github.com/wooorm/lowlight#lowlightregistergrammars508 509[lowlight-register-alias]: https://github.com/wooorm/lowlight#lowlightregisteraliasaliases510 511[npm]: https://docs.npmjs.com/cli/install512 513[rehype]: https://github.com/rehypejs/rehype514 515[rehype-highlight-code-lines]: https://github.com/ipikuka/rehype-highlight-code-lines516 517[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize518 519[rehype-starry-night]: https://github.com/rehypejs/rehype-starry-night520 521[size]: https://bundlejs.com/?q=rehype-highlight522 523[size-badge]: https://img.shields.io/bundlejs/size/rehype-highlight524 525[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg526 527[support]: https://github.com/rehypejs/.github/blob/HEAD/support.md528 529[typescript]: https://www.typescriptlang.org530 531[unified]: https://github.com/unifiedjs/unified532 533[unified-transformer]: https://github.com/unifiedjs/unified#transformer534