feat(transformers): render indent guides (#1060)

Co-authored-by: Anthony Fu <[email protected]>

Author: KazariEX

docs/.vitepress/theme/transformers.css

@@ -15,6 +15,27 @@ pre.shiki .space::before {
   opacity: 0.3;
 }
 
+pre.shiki .indent {
+  display: inline-block;
+  position: relative;
+  left: var(--indent-offset);
+  text-indent: 0;
+}
+
+pre.shiki .indent:empty {
+  height: 1lh;
+  vertical-align: bottom;
+}
+
+pre.shiki .indent::before {
+  content: '';
+  position: absolute;
+  opacity: 0.15;
+  width: 1px;
+  height: 100%;
+  background-color: currentColor;
+}
+
 pre.shiki .highlighted-word {
   background-color: var(--vp-c-bg-soft);
   border: 1px solid var(--vp-c-border);

docs/packages/transformers.md

@@ -358,6 +358,48 @@ pre.shiki .space::before {
 
 ---
 
+### `transformerRenderIndentGuides`
+
+Render indentations as individual spans, with class `indent`.
+
+With some additional CSS rules, you can make it look like this:
+
+<div class="language-js vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre v-pre class="shiki shiki-themes vitesse-light vitesse-dark" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;" tabindex="0"><code><span class="line"><span style="color:#CB7676">function</span><span style="color:#80A665"> func</span><span style="color:#666666">()</span><span style="color:#666666"> {</span></span>
+<span class="line"><span class="indent">  </span><span style="color:#BD976A">console</span><span style="color:#666666">.</span><span style="color:#80A665">log</span><span style="color:#666666">(</span><span style="color:#4C9A91">1</span><span style="color:#666666">);</span></span>
+<span class="line"><span class="indent" style="--indent-offset: 0ch;"></span></span>
+<span class="line"><span class="indent">  </span><span style="color:#4D9375">for</span><span style="color:#666666"> (</span><span style="color:#CB7676">const </span><span style="color:#BD976A">i</span><span style="color:#CB7676"> of</span><span style="color:#666666"> [])</span><span style="color:#666666"> {</span></span>
+<span class="line"><span class="indent">  </span><span class="indent">  </span><span style="color:#BD976A">console</span><span style="color:#666666">.</span><span style="color:#80A665">log</span><span style="color:#666666">(</span><span style="color:#4C9A91">2</span><span style="color:#666666">);</span></span>
+<span class="line"><span class="indent">  </span><span style="color:#666666">}</span></span>
+<span class="line"><span style="color:#666666">}</span></span></code></pre></div>
+
+::: details Example CSS
+
+```css
+pre.shiki .indent {
+  display: inline-block;
+  position: relative;
+  left: var(--indent-offset);
+}
+
+pre.shiki .indent:empty {
+  height: 1lh;
+  vertical-align: bottom;
+}
+
+pre.shiki .indent::before {
+  content: '';
+  position: absolute;
+  opacity: 0.15;
+  width: 1px;
+  height: 100%;
+  background-color: currentColor;
+}
+```
+
+:::
+
+---
+
 ### `transformerMetaHighlight`
 
 Highlight lines based on the [meta string](/guide/transformers#meta) provided on the code snippet.

packages/transformers/src/index.ts

@@ -11,5 +11,6 @@ export * from './transformers/notation-highlight-word'
 export * from './transformers/notation-map'
 export * from './transformers/remove-line-breaks'
 export * from './transformers/remove-notation-escape'
+export * from './transformers/render-indent-guides'
 export * from './transformers/render-whitespace'
 export * from './transformers/style-to-class'

packages/transformers/src/transformers/render-indent-guides.ts

@@ -0,0 +1,87 @@
+import type { ShikiTransformer } from '@shikijs/types'
+import type { Element } from 'hast'
+
+export interface TransformerRenderIndentGuidesOptions {
+  indent?: number
+}
+
+/**
+ * Render indentations as separate tokens.
+ * Apply with CSS, it can be used to render indent guides visually.
+ */
+export function transformerRenderIndentGuides(
+  options: TransformerRenderIndentGuidesOptions = {},
+): ShikiTransformer {
+  return {
+    name: '@shikijs/transformers:render-indent-guides',
+    code(hast) {
+      let { indent = 2 } = options
+
+      const match = this.options.meta?.__raw?.match(/\{indent:(\d+|false)\}/)
+      if (match) {
+        if (match[1] === 'false') {
+          return hast
+        }
+        indent = Number(match[1])
+      }
+      const indentRegex = new RegExp(` {${indent}}| {0,${indent - 1}}\t| {1,}$`, 'g')
+
+      const emptyLines: [Element, number][] = []
+      let level = 0
+
+      for (const line of hast.children) {
+        if (line.type !== 'element') {
+          continue
+        }
+
+        const first = line.children[0]
+        if (first?.type !== 'element' || first?.children[0]?.type !== 'text') {
+          emptyLines.push([line, level])
+          continue
+        }
+
+        const text = first.children[0]
+        const blanks = text.value.split(/[^ \t]/, 1)[0]
+
+        const ranges: [number, number][] = []
+        for (const match of blanks.matchAll(indentRegex)) {
+          const start = match.index
+          const end = start + match[0].length
+          ranges.push([start, end])
+        }
+
+        for (const [line, level] of emptyLines) {
+          line.children.unshift(...Array.from({ length: Math.min(ranges.length, level + 1) }, (_, i) => ({
+            type: 'element',
+            tagName: 'span',
+            properties: {
+              class: 'indent',
+              style: `--indent-offset: ${i * indent}ch;`,
+            },
+            children: [],
+          } satisfies Element)))
+        }
+        emptyLines.length = 0
+        level = ranges.length
+
+        if (ranges.length) {
+          line.children.unshift(
+            ...ranges.map(([start, end]) => ({
+              type: 'element',
+              tagName: 'span',
+              properties: {
+                class: 'indent',
+              },
+              children: [{
+                type: 'text',
+                value: text.value.slice(start, end),
+              }],
+            } satisfies Element)),
+          )
+          text.value = text.value.slice(ranges.at(-1)![1])
+        }
+      }
+      return hast
+    },
+  }
+}

test/exports/@shikijs/transformers.yaml

@@ -14,5 +14,6 @@
   transformerNotationWordHighlight: function
   transformerRemoveLineBreak: function
   transformerRemoveNotationEscape: function
+  transformerRenderIndentGuides: function
   transformerRenderWhitespace: function
   transformerStyleToClass: function