markdown-it-shiki-twoslash

A markdown-it plugin for Shiki with Twoslash code samples

Usage no npm install needed!

<script type="module">
  import markdownItShikiTwoslash from 'https://cdn.skypack.dev/markdown-it-shiki-twoslash';
</script>

README

markdown-it-shiki-twoslash

Sets up markdown code blocks to run through shiki which means it gets the VS Code quality syntax highlighting mixed with the twoslash JavaScript tooling from the TypeScript website.

Plugin Setup

  1. Install the dependency: yarn add markdown-it-shiki-twoslash

  2. Include "markdown-it-shiki-twoslash" in the plugins section of the markdown-it parser:

    import shikiTwoslash from "markdown-it-shiki-twoslash"
import MarkdownIt from "markdown-it"

const md = MarkdownIt()
md.use(shikiTwoslash, { theme: "nord" })

const html = md.render(file)

    or even better:

    import { markdownItShikiTwoslashSetup } from "markdown-it-shiki-twoslash"
import MarkdownIt from "markdown-it"

const md = MarkdownIt()

const shiki = await markdownItShikiTwoslashSetup({
  theme: "nord",
})

md.use(shiki)
const html = md.render(file)

    Because shiki uses WASM to handle the syntax highlighting, it has to be async code, this clashes with the markdown-it API which enforces synchronous code. In the first code sample, the plugin uses deasync to convert that async work to sync. It's safe to say that you probably don't want deasync'd code in critical systems.

  3. Follow the steps in npmjs.com/package/remark-shiki-twoslash to add the CSS requirements.

  4. Follow the instructions on npmjs.com/package/remark-shiki-twoslash, this module leaves all the heavy lifting to that module.