# @bitmachina/highlighter

> Highlight MDsveX files with the Shiki highlighter

Latest version **1.0.0-alpha.5** (published 2023-01-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @bitmachina/highlighter
pnpm add @bitmachina/highlighter
yarn add @bitmachina/highlighter
bun add @bitmachina/highlighter
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.0.0-alpha.5 |
| Published | 2023-01-02 |
| First published | 2023-01-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 24.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | John Hooks |
| Maintainers | bitmachina |
| Keywords | mdsvex, shiki, highlight, svelte, markdown |

## Links

- npm: https://www.npmjs.com/package/@bitmachina/highlighter
- Repository: https://github.com/johnhooks/highlighter
- Issues: https://github.com/johnhooks/highlighter/issues
- npm.io page: https://npm.io/package/@bitmachina/highlighter

## Dependencies (8)

- [shiki](https://npm.io/package/shiki.md) 0.11.1
- [unified](https://npm.io/package/unified.md) 10.1.2
- [hastscript](https://npm.io/package/hastscript.md) 7.1.0
- [rehype-parse](https://npm.io/package/rehype-parse.md) 8.0.4
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) 4.1.1
- [hast-util-to-html](https://npm.io/package/hast-util-to-html.md) 8.0.3
- [hast-util-to-string](https://npm.io/package/hast-util-to-string.md) 2.0.0
- [parse-numeric-range](https://npm.io/package/parse-numeric-range.md) 1.3.0

## Alternatives

- [@oh-my-pi/pi-natives](https://npm.io/package/@oh-my-pi/pi-natives.md) — 51.8K weekly downloads
- [@capgo/capacitor-light-sensor](https://npm.io/package/@capgo/capacitor-light-sensor.md) — 3.0K weekly downloads
- [@heyhuynhgiabuu/pi-diff](https://npm.io/package/@heyhuynhgiabuu/pi-diff.md) — 492 weekly downloads
- [@lotsa/verdant-lang-asm](https://npm.io/package/@lotsa/verdant-lang-asm.md) — 38 weekly downloads
- [new-era-syntax](https://npm.io/package/new-era-syntax.md) — 20 weekly downloads

## Recent versions

- 1.0.0-alpha.5 (latest) — 2023-01-02
- 1.0.0-alpha.7 (alpha) — 2023-02-12
- 1.0.0-alpha.6 — 2023-01-03

## README

# Highlight code in MDsveX with Shiki

> Use [Shiki](https://shiki.matsu.io/) to highlight code blocks in [MDSvex](https://mdsvex.com/) files.

## 📦 Install

```sh
npm install @bitmachina/highlighter@alpha

# or

yarn add @bitmachina/highlighter@alpha
```

## ⚡️ Quick start

The `createHighlighter` function takes an argument of Shiki `HighlighterOptions`.

Any [Shiki theme](https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes) can be used. This example uses the `css-variables` theme, which is really flexible.

```js
// mdsvex.config.js
import { createHighlighter } from "@bitmachina/highlighter";

/** @type {import('mdsvex').MdsvexOptions} */
export default {
  extensions: [".svelte.md", ".md", ".svx"],
  highlight: {
    highlighter: await createHighlighter({ theme: "css-variables" }),
  },
};
```

If using the `css-variables` theme, add the variables to your css.

```css
/* app.css */
:root {
  --shiki-color-background: #27272a;
  --shiki-color-text: #fff;
  --shiki-token-constant: #6ee7b7;
  --shiki-token-string: #6ee7b7;
  --shiki-token-comment: #71717a;
  --shiki-token-keyword: #7dd3fc;
  --shiki-token-parameter: #f9a8d4;
  --shiki-token-function: #c4b5fd;
  --shiki-token-string-expression: #6ee7b7;
  --shiki-token-punctuation: #e4e4e7;
}
```

## Meta strings

Code blocks are configured via the meta string on the top codeblock fence.

Some features have been added to make this package comparable to [Rehype Pretty Code](https://rehype-pretty-code.netlify.app/).

### Titles

Add a file title to your code block, with text inside double quotes (`""`):

````md
```js title="..."
```
````

This directive will add a `data-code-title` attribute to the `pre` element.

### Line numbers

By default line numbers are made available though the `data-line-number` attribute on the `span` elements containing lines.

Below is an example of adding line numbers to the code block using CSS and the data attributes.

```css
/* Example of adding line numbers to code blocks using CSS and the data attributes. */
code[data-line-numbers] > span[data-line-number]::before {
  /* Insert the line number data attribute before the line */
  content: attr(data-line-number);

  /* Other styling */
  display: inline-block;
  width: 1rem;
  margin-right: 1rem;
  margin-left: 1rem;
  text-align: right;
  color: gray;
}
```

If you want to conditionally show lines, use the `showLineNumbers` directive.

````md
```js showLineNumbers
  // <code> will have a `data-line-numbers` attribute
```
````

A starting line number can be provided as an argument to `showLineNumbers`.

````md
```js showLineNumbers{64}
// the first line of this code block will start at {number}
```
````

### Highlight lines

Place a numeric range inside `{}`.

````md
```js {1-3,4}
// lines 1,2,3 and 4 will have the `data-highlighted`
```
````

Below is an example of how to highlight lines using CSS and the `data-highlighted` attribute.

```css
code > span[data-highlighted] {
  background: #3b4252;
  width: 100%;
}
```

## Notes

If languages are known ahead of time, limiting them should speed up loading the highlighter.

```js
// mdsvex.config.js
export default {
  // ...rest of the MDsveX options
  highlight: {
    highlighter: createHighlighter({
      //  ...rest of the Shiki options
      lang: ["css", "html", "js", "ts", "sh"]
     }),
  },
};
```

## References

- The rendering was inspired by Shiki's [renderToHtml](https://github.com/shikijs/shiki/blob/a585c9d6860334a6233ff1c035a42d023e016400/packages/shiki/src/renderer.ts) function.
- The metadata parsing was inspired by [Rehype Pretty Code](https://github.com/atomiks/rehype-pretty-code).
- More information on theming: [Shiki - Theming with CSS Variables](https://github.com/shikijs/shiki/blob/main/docs/themes.md#theming-with-css-variables)

## License

MIT

---
_Source: https://npm.io/package/@bitmachina/highlighter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._