# Getting started
Package: @mantine/code-highlight
Description: Get started with @mantine/code-highlight package

## Installation

```bash
yarn add @mantine/code-highlight
```

```bash
npm install @mantine/code-highlight
```

After installation import package styles at the root of your application:

```tsx
import '@mantine/core/styles.css';
// ‼️ import code-highlight styles after core package styles
import '@mantine/code-highlight/styles.css';
```

## Adapters

`@mantine/code-highlight` does not depend on a specific highlighting library.
Choose one of the built-in adapters or create your own:

* `createShikiAdapter` – creates [shiki](https://shiki.matsu.io/) adapter
* `createHighlightJsAdapter` – creates [highlight.js](https://highlightjs.org/) adapter
* `plainTextAdapter` – does not highlight code, just displays it as plain text (used by default if no adapter is provided)

## Usage with shiki

[Shiki](https://shiki.matsu.io/) uses the same textmate grammars as VSCode and gives the most accurate highlighting.
It is recommended for TypeScript and CSS code and is used in Mantine documentation.

Install the `shiki` package:

```bash
yarn add shiki
```

```bash
npm install shiki
```

Then wrap your app with `CodeHighlightAdapterProvider` and provide `createShikiAdapter` as the `adapter` prop:

```tsx
import { MantineProvider } from '@mantine/core';
import { CodeHighlightAdapterProvider, createShikiAdapter } from '@mantine/code-highlight';

// Shiki requires async code to load the highlighter
async function loadShiki() {
  const { createHighlighter } = await import('shiki');
  const shiki = await createHighlighter({
    langs: ['tsx', 'scss', 'html', 'bash', 'json'],
    // You can load supported themes here
    themes: [],
  });

  return shiki;
}

const shikiAdapter = createShikiAdapter(loadShiki);

function App() {
  return (
    <MantineProvider>
      <CodeHighlightAdapterProvider adapter={shikiAdapter}>
        {/* Your app here */}
      </CodeHighlightAdapterProvider>
    </MantineProvider>
  );
}
```

## Lazy languages loading

By default, shiki loads grammars of all languages passed to the highlighter upfront.
To load grammars on demand, pass `resolveLanguage` option to `createShikiAdapter`.
Its return value is passed to shiki `highlighter.loadLanguage`, code is displayed as plain text until the grammar is loaded:

```tsx
import { createShikiAdapter } from '@mantine/code-highlight';

async function loadShiki() {
  const { createHighlighter } = await import('shiki');
  return createHighlighter({ langs: ['tsx'], themes: [] });
}

// Bundled highlighter resolves grammars by language name on its own
const shikiAdapter = createShikiAdapter(loadShiki, {
  resolveLanguage: (language) => language,
});
```

Highlighters created with `shiki/core` do not bundle grammars – return a function that imports
the grammar of the given language instead:

```tsx
import { createShikiAdapter } from '@mantine/code-highlight';

const grammars: Record<string, () => Promise<any>> = {
  python: () => import('@shikijs/langs/python'),
  ruby: () => import('@shikijs/langs/ruby'),
};

async function loadShiki() {
  const { createHighlighterCore } = await import('shiki/core');
  const { createJavaScriptRegexEngine } = await import('shiki/engine/javascript');

  return createHighlighterCore({
    langs: [],
    themes: [],
    engine: createJavaScriptRegexEngine(),
  });
}

const shikiAdapter = createShikiAdapter(loadShiki, {
  resolveLanguage: (language) => grammars[language],
});
```

If `resolveLanguage` returns `null` or `undefined`, the language is considered unsupported and
its code is displayed as plain text.

## Unavailable languages

Code in a language that is not loaded is displayed as plain text, a warning is logged in development.
To fix it, add the language to the `langs` option of the highlighter or load it with `resolveLanguage`.

## Usage with highlight.js

[Highlight.js](https://highlightjs.org/) is less accurate than shiki but has a smaller bundle size.
Choose it for basic JavaScript, HTML and CSS code.

Install the `highlight.js` package:

```bash
yarn add highlight.js
```

```bash
npm install highlight.js
```

Then wrap your app with `CodeHighlightAdapterProvider` and provide `createHighlightJsAdapter` as the `adapter` prop:

```tsx
import { MantineProvider } from '@mantine/core';
import { CodeHighlightAdapterProvider, createHighlightJsAdapter } from '@mantine/code-highlight';
import hljs from 'highlight.js/lib/core';
import tsLang from 'highlight.js/lib/languages/typescript';

hljs.registerLanguage('typescript', tsLang);

const highlightJsAdapter = createHighlightJsAdapter(hljs);

function App() {
  return (
    <MantineProvider>
      <CodeHighlightAdapterProvider adapter={highlightJsAdapter}>
        {/* Your app here */}
      </CodeHighlightAdapterProvider>
    </MantineProvider>
  );
}
```

Then add one of the highlight.js themes, either as a css import from the `highlight.js` package or as a CDN link:

```html
<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css"
/>
```

## Create custom adapter

Create a custom adapter to use another library or to extend the default behavior.
Example of a shiki adapter with custom themes and transformers:

```tsx
import { type CodeHighlightAdapter, stripShikiCodeBlocks } from '@mantine/code-highlight';

// Shiki transformers can be used to highlight diffs and other notations
// https://shiki.style/packages/transformers
import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers'

// Shiki themes as objects, you can use any VSCode themes
import { darkTheme, lightTheme } from './shiki-themes';

async function loadShiki() {
  const { createHighlighter } = await import('shiki');
  const shiki = await createHighlighter({
    langs: ['tsx', 'scss', 'html', 'bash', 'json'],
    themes: [],
  });

  return shiki;
}

// Pass this adapter to CodeHighlightAdapterProvider component
export const customShikiAdapter: CodeHighlightAdapter = {
  // loadContext is called on the client side to load the shiki highlighter
  // It is required to be used if your library requires async initialization
  // The value returned from loadContext is passed to getHighlighter as ctx argument
  loadContext: loadShiki,

  // ctx is the value returned from loadContext
  // or null if loadContext is not used or has not resolved yet
  getHighlighter: (ctx) => {
    if (!ctx) {
      return ({ code }) => ({ highlightedCode: code, isHighlighted: false });
    }

    return ({ code, language, colorScheme }) => ({
      isHighlighted: true,
      // stripShikiCodeBlocks removes <pre> and <code> tags from highlighted code
      highlightedCode: stripShikiCodeBlocks(
        ctx.codeToHtml(code, {
          lang: language,
          theme: (colorScheme === 'light' ? lightTheme : darkTheme) as any,
          transformers: [transformerNotationDiff(), transformerNotationHighlight()],
        })
      ),
    });
  },
};
```
