README.md

carbonplan / prism

components for syntax highlighting

Components for syntax highlighting using prism. Includes a Code component for rendering code and a LiveCode component for interactively editing JavaScript and viewing the results. Pairs well with MDX.

See these components demoed at design.carbonplan.org.

basic usage

To use as a standalone component, just provide the language and pass the code as children.

import { Code, LiveCode } from '@carbonplan/prism'

export const Index = () => {
  return <>
  	<Code language='python'>a = 2</Code>
  	<LiveCode language='jsx' live>let a = 2</Code>
  </>
}

When using the LiveCode component you must specify the live flag to include the live editor. Otherwise it will render using the basic Code component as a fallback. We require setting the flag so that you can use the LiveCode component with MDX for a mix of both live and static code.

usage with MDX

In order to use markdown meta props like live and theme discussed below, note that you will need to use remark-mdx-code-meta or another solution for syntax highlighting with the meta field.

Once enabled, import the component(s) you want and pass to an MDXProvider.

import { MDXProvider } from '@mdx-js/react'
import { LiveCode } from '@carbonplan/prism'

const components = {
  pre: LiveCode,
}

return <MDXProvider components={components}>...</MDXProvider>

So long as you are using the LiveCode component, you can specify a live flag on a code fence in MDX and get a live code editor.

This will be rendered as normal code

```jsx
const a = 2
```

This will be rendered as a live code editor

```jsx live
const a = 2
```

color schemes

Both the Code and LiveCode components take an optional theme property which specifies one of a fixed set of color themes via a string name. Here they are.

monochrome

polychrome

triadic

warm

cool

You can set the theme once when defining the component, like this.

import { MDXProvider } from '@mdx-js/react'
import { Code } from '@carbonplan/prism'

const components = {
  pre: ({ ...props }) => <Code theme='polychrome' {...props} />,
}

return <MDXProvider components={components}>...</MDXProvider>

This will then apply to all code rendered via MDX.

You can also specify a different theme on an individual code fence, which will override the one set on the component.

For example, this will be rendered in the monochrome theme

```jsx theme=monochrome
const a = 2
```

And this will be rendered in the polychrome theme

```jsx theme=polychrome
const a = 2
```

live code options

The LiveCode component also takes optional scope and transform properties. The scope specifies the variables you want to be available in the scope of the code editor, and the transform is a function to apply to code before execution.

As an example, the following ensures that all code is interpreted as a React fragment unless it is a function, and adds useState to the scope. Note that we set these properties while defining the component passed to the MDXProvider.

import { useState } from 'react'
import { MDXProvider } from '@mdx-js/react'
import { LiveCode } from '@carbonplan/prism'

const transform = (src) => {
  if (!src.startsWith('()')) {
    return `<>${src}</>`
  } else {
    return `${src}`
  }
}

const scope = {
  useState,
}

const components = {
  pre: ({ ...props }) => (
    <LiveCode transform={transform} scope={scope} {...props} />
  ),
}

return <MDXProvider components={components}>...</MDXProvider>

development

To update a component and publish a new version, first make your changes, then follow these steps

• Increase the version number in package.json
• npm run build
• npm publish

license

All the code in this repository is MIT-licensed, but we request that you please provide attribution if reusing any of our digital content (graphics, logo, articles, etc.).

about us

CarbonPlan is a nonprofit organization that uses data and science for climate action. We aim to improve the transparency and scientific integrity of climate solutions with open data and tools. Find out more at carbonplan.org or get in touch by opening an issue or sending us an email.