shiki-hide-lines

A Shiki transformer that hides marked lines from rendered code blocks while keeping them in the source.

Hide boilerplate (imports, setup, autoloading) that is necessary for execution but distracting for readers.

Install

npm install shiki-hide-lines

Usage

Syntax

Mark single lines with // [!code hide] or # [!code hide]:

<?php // [!code hide]
declare(strict_types=1); // [!code hide]
require_once 'vendor/autoload.php'; // [!code hide]
use App\Models\User; // [!code hide]

$user = User::find(1);
echo $user->name;

import os # [!code hide]
from pathlib import Path # [!code hide]

print(Path.home())

Rendered output shows only the meaningful lines.

Use block markers to hide ranges:

// [!code hide:start]
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
// [!code hide:end]

createApp(App).use(router).mount('#app')

# [!code hide:start]
version: '3.8'
services:
# [!code hide:end]
  web:
    image: nginx:alpine
    ports:
      - '8080:80'

The comment marker adapts to the language:

Marker	Languages
//	PHP, JavaScript, TypeScript, Go, Rust, Java, C
#	Python, Ruby, Bash, YAML, Perl, Dockerfile, Elixir
--	SQL, Lua, Haskell, Elm
%	LaTeX, TeX, Erlang
;	Lisp, Scheme, Clojure, ASM

Modes

Fully Hidden (default) — marked lines are completely removed from output:

import { codeToHtml } from 'shiki'
import { transformerHideLines } from 'shiki-hide-lines'

const html = await codeToHtml(code, {
  lang: 'php',
  theme: 'github-dark',
  transformers: [transformerHideLines()]
})

Revealable — marked lines are collapsed behind a clickable placeholder:

transformerHideLines({ reveal: true })

In reveal mode, a ··· N hidden lines placeholder appears. Clicking it expands the hidden lines and changes the text to ▲ N hidden lines. Clicking again collapses them back.

Custom Placeholder Text

Customize the collapsed and expanded placeholder text:

String template — use {count} for the line count:

transformerHideLines({
  reveal: true,
  summaryTemplate: '▶ {count} lines collapsed',
  expandedSummaryTemplate: '▼ {count} lines shown'
})
// Collapsed: ▶ 3 lines collapsed
// Expanded:  ▼ 3 lines shown

Function — full control for i18n or pluralization:

transformerHideLines({
  reveal: true,
  summaryTemplate: (count) =>
    count === 1 ? '1 ligne masquée' : `${count} lignes masquées`,
  expandedSummaryTemplate: (count) =>
    count === 1 ? '▲ 1 ligne' : `▲ ${count} lignes`
})

Custom Marker

Change the marker keyword (default: hide):

transformerHideLines({ marker: 'hidden' })
// Uses: // [!code hidden] and // [!code hidden:start] / // [!code hidden:end]

Integration

VitePress

// .vitepress/config.ts
import { transformerHideLines } from 'shiki-hide-lines'

export default defineConfig({
  markdown: {
    codeTransformers: [
      transformerHideLines({ reveal: true })
    ]
  }
})

Astro

// astro.config.mjs
import { transformerHideLines } from 'shiki-hide-lines'

export default defineConfig({
  markdown: {
    shikiConfig: {
      transformers: [transformerHideLines()]
    }
  }
})

Nuxt Content

// nuxt.config.ts
import { transformerHideLines } from 'shiki-hide-lines'

export default defineNuxtConfig({
  content: {
    highlight: {
      transformers: [transformerHideLines()]
    }
  }
})

Reveal Mode Setup

Reveal mode requires CSS and a small client-side script for the toggle interaction.

CSS

Import the default stylesheet:

import 'shiki-hide-lines/style.css'

Or add it to your CSS manually. The styles use these classes:

Class	Element	Description
has-hidden-lines	<pre>	Code block contains hidden lines
hidden-line	<span class="line">	A hidden line
hidden-lines-summary	<span>	Clickable placeholder (role="button")
hidden-lines-revealed	<pre>	Toggled to expanded state
hidden-lines-collapsed-text	<span>	Text shown when collapsed
hidden-lines-expanded-text	<span>	Text shown when expanded

The default styles respect --vp-code-tab-text-color and --vp-c-brand CSS custom properties for theme compatibility.

Client Script

The toggle requires event delegation for click and keyboard interaction. Choose one:

Option A — Inline script (SSG/SSR sites):

import { getToggleScript } from 'shiki-hide-lines'

// Inject into your page <head> or layout
const script = `<script>${getToggleScript()}</script>`

Option B — Direct import (SPA/client-side, e.g. VitePress):

import { setupHiddenLinesToggle } from 'shiki-hide-lines'

setupHiddenLinesToggle()

Both options register click and keyboard (Enter/Space) handlers with full ARIA support.

Accessibility

Reveal mode follows the ARIA disclosure pattern:

• Summary elements have role="button" and tabindex="0" for keyboard access
• aria-expanded reflects the current toggle state
• aria-label describes the action (e.g. "Toggle 3 hidden lines")
• Enter and Space keys trigger the toggle
• Focus indicator appears on keyboard navigation (:focus-visible)

API

function transformerHideLines(options?: HideLinesOptions): ShikiTransformer

Options

Option	Type	Default	Description
reveal	boolean	false	Enable reveal mode with clickable placeholders
marker	string	'hide'	The marker keyword in [!code <marker>]
summaryTemplate	string | (count: number) => string	'··· N hidden line(s)'	Customize collapsed placeholder text. Use {count} in strings
expandedSummaryTemplate	string | (count: number) => string	'▲ N hidden line(s)'	Customize expanded placeholder text. Use {count} in strings

Exports

Export	Description
transformerHideLines	The Shiki transformer factory
getToggleScript	Returns toggle script as a string (for inline injection)
setupHiddenLinesToggle	Registers click and keyboard handlers (for SPA use)
HideLinesOptions	TypeScript options interface

License

MIT