- A lean Prism highlighter component for React
- Comes with everything to render Prismjs highlighted code directly to React (Native) elements, global-pollution-free!
+ A lean Prism highlighter component for React
-Maybe you need to render some extra UI with your Prismjs-highlighted code,
-or maybe you'd like to manipulate what Prism renders completely,
-or maybe you're just using Prism with React and are searching for an easier,
-global-pollution-free way?
+
+ Comes with everything to render Prismjs syntax highlighted code directly in React & React Native!
+
-Then you're right where you want to be!
+## Introduction
-## How?
+Prism React Renderer powers syntax highlighting in the amazing [Docusaurus](https://docusaurus.io/) framework and many others.
This library tokenises code using Prism and provides a small render-props-driven
component to quickly render it out into React. This is why it even works with
@@ -36,8 +39,6 @@ _(If you just want to use your Prism CSS-file themes, that's also no problem)_
## Table of Contents
-
-
- [Installation](#installation)
- [Usage](#usage)
@@ -54,7 +55,19 @@ _(If you just want to use your Prism CSS-file themes, that's also no problem)_
- [prop getters](#prop-getters)
- [`getLineProps`](#getlineprops)
- [`getTokenProps`](#gettokenprops)
+- [Utility Functions](#utility-functions)
+ - [`useTokenize`](#usetokenize)
+ - [`normalizeTokens`](#normalizetokens)
- [Theming](#theming)
+ - [Using a built-in theme](#using-a-built-in-theme)
+ - [Providing a CSS based theme](#providing-a-css-based-theme)
+- [Upgrade](#upgrade)
+ - [Change module imports](#change-module-imports)
+ - [Change theme imports](#change-theme-imports)
+ - [Check language support](#check-language-support)
+ - [Add language component](#add-language-component)
+- [Development](#development)
+ - [Local Demo](#local-demo)
- [LICENSE](#license)
- [Maintenance Status](#maintenance-status)
@@ -77,7 +90,8 @@ pnpm add prism-react-renderer
> Prism React Renderer has a peer dependency on `react`
### Usage
-Prism React Renderer has a named export for the `` component along with `themes`. To see Prism React Render in action with base styling check out `packages/demo` or run `pnpm run start:demo` from the root of this repository.
+
+Prism React Renderer has a named export for the `` component along with `themes`. To see Prism React Render in action with base styling, clone the repo and follow the [steps for local development](#development).
```tsx
import React from "react"
@@ -118,14 +132,18 @@ export const App = () => (
)
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement)
- .render()
-
+ReactDOM
+ .createRoot(document.getElementById("root") as HTMLElement)
+ .render()
```
### Custom Language Support
-By default `prism-react-renderer` only includes a [base set of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/c914fdea48625ba59c8022174bb3df1ed802ce4d/packages/generate-prism-languages/index.ts#L9-L23) that Prism supports. **Depending on your app's build system you may need to `await` the `import` or use `require` to ensure `window.Prism` exists before importing the custom languages.** You can add support for more by including their definitions from the main `prismjs` package:
+By default `prism-react-renderer` only includes a [base set of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/generate-prism-languages/index.ts#L9-L23) that Prism supports.
+
+> _Note_: Some languages (such as Javascript) are part of the bundle of other languages
+
+**Depending on your app's build system you may need to `await` the `import` or use `require` to ensure `window.Prism` exists before importing the custom languages.** You can add support for more by including their definitions from the main `prismjs` package:
```js
import { Highlight, Prism } from "prism-react-renderer";
@@ -253,7 +271,7 @@ advisable.
#### `getLineProps`
You need to add a `line` property (type: `Token[]`) to the object you're passing to
-`getLineProps`; It's also advisable to add a `key`.
+`getLineProps`.
This getter will return you props to spread onto your line elements (typically `
s`).
@@ -266,7 +284,7 @@ The `className` will always contain `.token-line`.
#### `getTokenProps`
You need to add a `token` property (type: `Token`) to the object you're passing to
-`getTokenProps`; It's also advisable to add a `key`.
+`getTokenProps`.
This getter will return you props to spread onto your token elements (typically `s`).
@@ -277,14 +295,50 @@ to the input.
The `className` will always contain `.token`. This also provides full compatibility with
your old Prism CSS-file themes.
+## Utility Functions
+
+### `useTokenize`
+
+> `(options: TokenizeOptions) => Token[][]`
+
+```ts
+type TokenizeOptions = {
+ prism: PrismLib
+ code: string
+ grammar?: PrismGrammar
+ language: Language
+}
+
+```
+
+This is a React hook that tokenizes code using Prism. It returns an array of tokens that can be rendered using the built-in `` component or your own custom component. It uses `normalizeTokens` internally to convert the tokens into a shape that can be rendered.
+
+- `prism: PrismLib`: the Prism library to use for tokenization. This can be the vendored version of Prism that is included with `prism-react-renderer` or a custom version of Prism that you have configured.
+
+- `code: string`: a string containing the code to tokenize.
+- `grammar?: PrismGrammar`: a Prism grammar object to use for tokenization. If this is omitted, the tokens will just be normalized. A grammar can be obtained from `Prism.languages` or by importing a language from `prismjs/components/`.
+- `language: Language`: the language to use for tokenization. This should be a language that Prism supports.
+
+### `normalizeTokens`
+
+> `(tokens: (PrismToken | string)[]) => Token[][]`
+
+Takes an array of Prism’s tokens and groups them by line, converting strings into tokens. Tokens can become recursive in some cases which means that their types are concatenated. Plain-string tokens however are always of type `plain`.
+
+- `PrismToken` is an internal alias for `Token` exported by `prismjs` and is defined [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/prismjs/index.d.ts#L347).
+
+- `Token` is an internal object that represents a slice of tokenized content for Prism with three properties:
+ - `types: string[]`: an array of types that indicate the purpose and styling of a piece of text
+ - `content: string`: the content of the token
+ - `empty: boolean`: a flag indicating whether the token is empty or not.
+
## Theming
+### Using a built-in theme
+
The `defaultProps` you'd typically apply in a basic use-case, contain a default theme.
This theme is [vsDark](./packages/prism-react-renderer/src/themes/vsDark.ts).
-While all `className`s are provided with ``, so that you could use your good
-old Prism CSS-file themes, you can also choose to use `prism-react-renderer`'s themes like so:
-
```jsx
import { Highlight, themes } from 'prism-react-renderer';
@@ -293,15 +347,13 @@ import { Highlight, themes } from 'prism-react-renderer';
These themes are JSON-based and are heavily inspired by VSCode's theme format.
-Their syntax, expressed in Flow looks like the following:
-
-```js
-{
- plain: StyleObj,
+```ts
+export type PrismTheme = {
+ plain: PrismThemeEntry
styles: Array<{ - types: string[], - languages?: string[], - style: StyleObj + types: string[] + style: PrismThemeEntry + languages?: Language[] }>
}
```
@@ -320,13 +372,105 @@ property limits styles to highlighted languages.
When converting a Prism CSS theme it's mostly just necessary to use classes as
`types` and convert the declarations to object-style-syntax and put them on `style`.
+### Providing a CSS based theme
+
+In order to use a CSS based theme like the ones from [PrismJS](https://github.com/PrismJS/prism-themes), you need to disable the built in theme.
+
+```ts
+const emptyTheme = { plain: {}, styles: [] };
+
+
+```
+
+## Upgrade
+
+If you are migrating from v1.x to v2.x, follow these steps
+
+### Change module imports
+
+```diff
+- import Highlight, { defaultProps } from "prism-react-renderer";
++ import { Highlight } from "prism-react-renderer"
+
+const Content = (
+-
++
+```
+
+### Change theme imports
+
+```diff
+- const theme = require('prism-react-renderer/themes/github')
++ const theme = require('prism-react-renderer').themes.github
+```
+
+### Check language support
+
+> By default prism-react-renderer only includes a base set of languages that Prism supports. Depending on your app's build system you may need to await the import or use require to ensure window.Prism exists before importing the custom languages.
+
+See: https://github.com/FormidableLabs/prism-react-renderer#custom-language-support
+
+Install prismjs (if not available yet):
+
+```
+# npm
+npm install --save prismjs
+# yarn
+yarn add prismjs
+# pnpm
+pnpm add prismjs
+```
+
+### Add language component
+
+If the language is not already bundled in the above, you can add additional languages with the following code:
+
+```
+import { Highlight, Prism } from "prism-react-renderer";
+
+(typeof global !== "undefined" ? global : window).Prism = Prism
+await import("prismjs/components/prism-applescript")
+/** or **/
+require("prismjs/components/prism-applescript")
+```
+
+## Development
+
+Local development setup can be run with the following commands running Node 18.x. This project uses corepack to specify its package manager version and you should have it enabled locally using `corepack enable`.
+
+```
+$ pnpm install
+$ pnpm build
+$ pnpm test
+```
+
+### Local Demo
+
+To run the local demo, ensure you have first run `pnpm build`, then run `pnpm start:demo` and open the provided URL to the demo site in your terminal.
+
+```
+$ pnpm build
+$ pnpm start:demo
+```
+
+The workspace projects are linked, so changes can be hot reloaded during development by running multiple terminals
+
+```
+// terminal 1
+$ pnpm build:watch
+```
+
+```
+// terminal 2
+$ pnpm start:demo
+```
+
## LICENSE
MIT
## Maintenance Status
-**Active:** Formidable is actively working on this project, and we expect to continue for work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.
+**Active:** Nearform is actively working on this project, and we expect to continue work for the foreseeable future. Bug reports, feature requests and pull requests are welcome.
[maintenance-image]: https://img.shields.io/badge/maintenance-active-green.svg
-
diff --git a/package.json b/package.json
index 2a43ff6..44f6976 100755
--- a/package.json
+++ b/package.json
@@ -50,5 +50,6 @@
"patchedDependencies": {
"prismjs@1.29.0": "patches/prismjs@1.29.0.patch"
}
- }
+ },
+ "packageManager": "pnpm@8.2.0+sha512.7f6fda6e5e86c9cc4b815650b56036cc124a31772fd8bf3a1c6470278aa74b4da05732e0b457a00b6e6a58a16d52e9c263be06530c6ad80ef2180244c8eb8262"
}
diff --git a/packages/demo/index.html b/packages/demo/index.html
index d42d119..c20c08d 100644
--- a/packages/demo/index.html
+++ b/packages/demo/index.html
@@ -2,10 +2,10 @@
-
+
- Formidable – Prism React Renderer Demo
+ Prism React Renderer Demo