@md-plugins/md-plugin-codeblocks

md-plugin-codeblocks

A Markdown-It plugin that enhances code block rendering by providing syntax highlighting, line numbering, and support for advanced features like tabbed code blocks. It integrates with Shiki for syntax highlighting and allows customization for various use cases.

Features

• Syntax Highlighting: Automatically highlights code blocks using Shiki.
• TwoSlash Hovers: Opt in to TypeScript-powered hover and query output for richer examples.
• Line Numbering: Optionally adds line numbers to code blocks.
• Magic Comments: Supports special comments like [[! highlight]], [[! add]], and [[! rem]] for inline code annotations.
• Tabbed Code Blocks: Enables the creation of tabbed code blocks for multi-language or multi-file examples.
• Customizable Components: Supports custom wrapper and copy button components.
• Fallback for Unsupported Languages: Gracefully handles code blocks written in unsupported languages.

Installation

Install the plugin via your preferred package manager:

# with pnpm:
pnpm add @md-plugins/md-plugin-codeblocks
# with bun:
bun add @md-plugins/md-plugin-codeblocks
# with Yarn:
yarn add @md-plugins/md-plugin-codeblocks
# with npm:
npm install @md-plugins/md-plugin-codeblocks

Usage

Basic Setup

import MarkdownIt from 'markdown-it'
import { codeblocksPlugin } from '@md-plugins/md-plugin-codeblocks'

const md = new MarkdownIt()
md.use(codeblocksPlugin, {
  containerComponent: 'MarkdownPrerender',
  copyButtonComponent: '<MarkdownCopyButton',
  preClass: 'markdown-code',
  pageScripts: [
    "import MarkdownPrerender from '@/.q-press/components/MarkdownPrerender'",
    "import MarkdownCopyButton from '@/.q-press/components/MarkdownCopyButton.vue'",
  ],
})

Example Markdown Input

console.log('Hello, world!')

Example Output

The rendered output will include syntax-highlighted code wrapped in customizable components:

<markdown-prerender>
  <pre v-pre class="markdown-code language-javascript">
    <code>
      console<span class="token punctuation">.</span>
      <span class="token function">log</span>
      <span class="token punctuation">(</span>
      <span class="token string">'Hello, world!'</span>
      <span class="token punctuation">)</span>
      <span class="token punctuation">;</span>
    </code>
  </pre>
  <markdown-copy-button></markdown-copy-button>
</markdown-prerender>

Options

The md-plugin-codeblocks plugin supports the following options:

Advanced Features

Line Numbering

The plugin supports magic comments for inline annotations:

```js [numbered]
// All lines will be numbered
console.log('Line 1')
console.log('Line 2')
console.log('Line 3')
```

TwoSlash Type Hovers

Add the twoslash attribute to TypeScript or JavaScript examples when you want inferred type information, compiler diagnostics, or ^? query output.

```ts [twoslash]
const count = 1
//    ^?
```

Code Block Height

Use maxheight when a long snippet should scroll inside the page. Use minheight when a short snippet needs more vertical room for overlays such as Twoslash hover popups.

```ts [twoslash minheight=12rem]
const selectedIcon = 'event' as const
//    ^?
```

Line Highlighting and Annotations

```js [highlight=2]
console.log('Line 1')
console.log('Line 2') // This line will be highlighted
console.log('Line 3')
```

```js
console.log('Line 1')
console.log('Line 2') [[highlight]] // This line will be highlighted
console.log('Line 3')
```

```js [add=2]
console.log('Line 1')
console.log('Line 2') // This line will be accented and prefixed with a '+'
console.log('Line 3')
```

```js [rem=2]
console.log('Line 1')
console.log('Line 2') // This line will be accented and prefixed with a '-'
console.log('Line 3')
```

Combining Annotations

```js [numbered highlight=1 rem=2 add=3]
console.log('Line 1') // This line will be highlighted
console.log('Line 2') // This line will be accented and prefixed with a '-'
console.log('Line 3') // This line will be accented and prefixed
```

Using Ranges

Additonally, with the exception of numbered, you can use ranges to annotate multiple lines:

[highlight=1,10-11 add=4,7-9 rem=12-14]

Tabbed Code Blocks

Easily create tabbed interfaces for multiple code examples:

When Q-Press renders the generated tab container, icon can select a bundled pnpm, npm, yarn, or bun icon. Other renderers may consume the generated tab-icons metadata themselves.

```tabs
<<|bash [icon=pnpm] pnpm|>>
pnpm add example-package

<<|bash [icon=npm] npm|>>
npm install example-package
```

Testing

Run the unit tests with Vitest:

pnpm test

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

Support

If md-plugin-codeblocks is useful in your workflow and you want to support ongoing maintenance:

• GitHub Sponsors: https://github.com/sponsors/hawkeye64
• PayPal: https://paypal.me/hawkeye64

License

This project is licensed under the MIT License. See the LICENSE file for details.