annotative

Icon generated with Stable Diffusion XL

Supercharge your highlight.js code demo with interactive input knobs

Quick links: Get Started | API Doc | Interactive Playground

Demos: React | Vue | Svelte | vanilla JS

Quick React.js example

npm i annotative-code -S

// 1. Because using web components in React is not mature yet
// we need to create a bridge React component <AnnotativeCode /> with `@lit/react`
import React from 'react';
import { createComponent } from '@lit/react';
import { AnnotativeCode as AnnotativeCodeWC } from 'annotative-code';

export const AnnotativeCode = createComponent({
  tagName: 'annotative-code',
  elementClass: AnnotativeCodeWC,
  react: React,
});

import { AnnotativeCode } from './AnnotativeCode';

// 2. Only import the language function and theme css in need can reduce the bundle size
import languageFn from 'annotative-code/bin/highlight.js/languages/javascript';
import themeCss from 'annotative-code/bin/highlight.js/css/a11y-dark';

// 3. Code/content to be highlighted
const content = `<Button variant="____variant____">
  Click me!
</Button>`;

// 4. Add annotations to the highlighted code!
const annotation = {
  variant: {
    type: 'string',
    knob: 'select',
    options: ['text', 'contained', 'outlined'],
    value: variant,
  },
};

<AnnotativeCode
  themeCss={themeCss}
  languageFn={languageFn}
  content={content}
  annotation={annotation}
  onValueChange={({ detail }) => setVariant(detail.valueObj.variant)}
/>;

Features

• 📝 Goodies of highlight.js - Syntax highlighting of 190+ programming languages and 240+ themes support
• 🎮 Interactive knobs - Let users play around with your code safely with various knobs e.g. string, number, select and datetime-local
• 👂🏻 On change listener - Captures user's input and reflect to the demo
• 🧙🏻‍♂️ Customizable - Code block styles (styleMap) and pop up (renderPopup and renderDescription) are customizable
• 🧱 Web component - Works with most of the frameworks e.g. React, Svelte, Vue and more

Development

(WIP)

1. (One time only) Install dependencies

npm install

The annotative package is built with lit and the local development environment is using vite.

2. (One time only) Generate lit theme CSS and programming languages functions from highlight.js

node ./tools/generateThemes
node ./tools/generateProgLangs

3. Run the dev server

npm run dev