Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/juanbzpy/mdx-prism
rehype plugin to highlight code blocks in HTML with Prism (via refractor)
https://github.com/juanbzpy/mdx-prism
Last synced: 3 months ago
JSON representation
rehype plugin to highlight code blocks in HTML with Prism (via refractor)
- Host: GitHub
- URL: https://github.com/juanbzpy/mdx-prism
- Owner: juanbzpy
- License: mit
- Created: 2019-06-03T17:26:33.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-03-06T07:21:17.000Z (almost 2 years ago)
- Last Synced: 2024-08-02T17:50:36.197Z (5 months ago)
- Language: JavaScript
- Homepage:
- Size: 851 KB
- Stars: 36
- Watchers: 1
- Forks: 11
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mdx-prism
This is a fork of [@mapbox/rehype-prism](https://github.com/mapbox/rehype-prism) that adds line highlighting capabilities, e.g.:
[rehype](https://github.com/wooorm/rehype) plugin to highlight code blocks in HTML with [Prism] (via [refractor]).
(If you would like to highlight code blocks with [highlight.js](https://github.com/isagalaev/highlight.js), instead, check out [rehype-highlight](https://github.com/wooorm/rehype-highlight).)
**Best suited for usage in Node.**
If you would like to perform syntax highlighting *in the browser*, you should look into [less heavy ways to use refractor](https://github.com/wooorm/refractor#browser).
## Installation
```
npm install mdx-prism
```
## API
`rehype().use(rehypePrism, [options])`
Syntax highlights `pre > code`.
Under the hood, it uses [refractor], which is a virtual version of [Prism].
The code language is configured by setting a `language-{name}` class on the `` element.
You can use any [language supported by refractor].
If no `language-{name}` class is found on a `` element, it will be skipped.
### options
#### options.ignoreMissing
Type: `boolean`.
Default: `false`.
By default, if `{name}` does not correspond to a [language supported by refractor] an error will be thrown.
If you would like to silently skip `` elements with invalid languages, set this option to `true`.
## Usage
Use this package [as a rehype plugin](https://github.com/rehypejs/rehype/blob/master/doc/plugins.md#using-plugins).
Some examples of how you might do that:
```js
const rehype = require('rehype');
const mdxPrism = require('mdx-prism');
rehype()
.use(mdxPrism)
.process(/* some html */);
```
```js
const unified = require('unified');
const rehypeParse = require('rehype-parse');
const mdxPrism = require('mdx-prism');
unified()
.use(rehypeParse)
.use(mdxPrism)
.processSync(/* some html */);
```
If you'd like to get syntax highlighting in Markdown, parse the Markdown (with remark-parse), convert it to rehype, then use this plugin.
```js
const unified = require('unified');
const remarkParse = require('remark-parse');
const remarkRehype = require('remark-rehype');
const mdxPrism = require('mdx-prism');
unified()
.use(remarkParse)
.use(remarkRehype)
.use(mdxPrism)
.process(/* some markdown */);
```
## FAQ
Why does mdx-prism copy the language- class to the <pre> tag?
[Prism recommends](https://prismjs.com/#basic-usage) adding the `language-` class to the `` tag like this:
```html
p { color: red }
```
It bases this recommendation on the HTML5 spec. However, an undocumented behavior of their JavaScript is that, in the process of highlighting the code, they also copy the `language-` class to the `
` tag:
```html
p { color: red }
```
This resulted in many [Prism themes](https://github.com/PrismJS/prism-themes) relying on this behavior by using CSS selectors like `pre[class*="language-"]`. So in order for people using mdx-prism to get the most out of these themes, we decided to do the same.
[Prism]: http://prismjs.com/
[refractor]: https://github.com/wooorm/refractor
[language supported by refractor]: https://github.com/wooorm/refractor#syntaxes