Md 文档代码块功能完备，以及自定义 meta 语法使用备忘

标签:Markdown, DX, memo, light-note
分类:备忘录
8分钟阅读

最前

博文渲染（Markdown -> Html）中，代码块的友好展示、功能完备，对于博客定位是涉及代码的技术向，是非常必要的。

本站点的代码块展示风格也在吾辈的数个开发版本迭代（当前博客主题版本：v0.1.34.55）下，自我评估已经具备能满足吾辈大多数日常使用情境的完整功能特性。

书写本文的动机

第一是吾辈先前逐步完备 MD 代码块功能过程中，实际也充分体现了在产品开发中：“从评估需求是否有充分被需要场景，到如何具体落地实现”，这样一个开发周期下的重要环节。中间对功能的探索以及实现的过程漫长，所以私心留个纪念；同时后文对本站代码块功能点的罗列，也对其他开发者/同好对代码块可支持功能点的探索有小小参考。

第二也是做个对本站书写 Markdown 代码块时自定义语法的备忘（本文实际更多承载着这样的角色，方便吾辈日后查询用）👉🏻 跳转到文末语法汇总小节。

背景

想要自主探索我们能够将代码块功能完备到什么程度，来自于 Meta 的 Docusaurus 文档建站开源作品下 官方文档的代码块章节是份质量很高的参考（甚至于激发开发者发现自己原本忽视的需求场景）

效果对比

本站对 markdown/mdx 文件的处理，主要基于 rehype/remark 等第三方库及其之下的生态插件。其中代码块的渲染，非常感谢来自 rehype 生态的开源插件： rehype-prism-plus——它提供了良好的代码语法高亮、行高亮等重要功能支持，也为吾辈之后定义 rehype / remark 插件提供了可靠的模仿参考来源。

现在，我们有如下一段代码：

```js:demo-code.js {1,3-4} showLineNumbers focusBlur maxH hidecode
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
```

分别提供如下三种对 MD 代码块的渲染效果对比：

  • 未使用任何 rehype / remark 插件，原生的代码块样式（可见此时语法高亮的功能是不具备的，我们需要额外的插件来解析代码块内容，匹配对应编程语言的语法，从而实现高亮）：
图例1
  • 仅使用 rehype-prism-plus 插件后，代码块样式：
图例2
  • 本站的基于多个吾辈自定义插件（以及相关联的样式表文件）后的最终代码块样式（hidecode 声明让其默认收起，这里需手动展开）：
demo-code.js

🤖 GPT 帮帮忙

正题

必要（或者显得必要的）功能特性罗列：

1.语言水印戳

对于不含标题的代码快，当前语言的水印戳（或者其他类似标记）是必要的，为阅读者强调/明晰当前使用的编程语言。

效果如下：

func() {
	sum := 0
	for i := 1; i <= 1e6; i++ { // 则当 `div.son` 元素水平过长，作用 div.par 的内容区可水平滚动时。那么此时 **#abs 元素会随着一起横向滚动** // 则当 `div.son` 元素水平过长，作用 div.par 的内容区可水平滚动时。那么此时 **#abs 元素会随着一起横向滚动**
		sum += i
	}
}()

2. 显示头部标题

该功能的支持显然非常必要。

3. 行号开启时，列固定在左侧

非常意外，rehype-prism-plus 插件并没有支持这个特性 —— 导致代码块横向过长滚动的情况下，行号会一起滚动。而在吾辈看来，这一点很有支持的必要。

保持其行号列固定也许带来更好观感。

4. 行高亮支持

更详细说明见本站另一博文《自定义 Markdown 代码块语法，通过注释声明高亮区域》；

rehype-prism-plus 默认提供了在代码块 meta 区域声明高亮行的语法，吾辈额外的基于 Docusaurus 源码，拓展了行高亮的声明语法 —— 使用行间注释声明。（此时基于 meta#{1,3-4} 的高亮行声明风格基本可以废弃不用）那么代码块可以如下使用：

使用风格：

```js:demo-code22.js showLineNumbers
// hl -11
var num1, num2, sum;
num1 = prompt("Enter first number");
// hl -00
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
// hl -99
alert("Sum = " + sum); // "+" means combine into a string
```

效果如下：

demo-code22.js
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string

5. 最大高度限制

一般的，博文中有些贴上的代码段可能是行数较多的，代码块折叠虽然可以解决这个问题，但是如果希望代码块展开之后，仍然不会占据页面纵向过多篇幅，那么应该对代码块最大高度限制。

本站通过代码块 meta#maxH 的显式声明，实现高度限制。

```js:demo-code33.js showLineNumbers maxH
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
```

效果如下：

demo-code33.js
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
// repeat code
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string

6. 代码块折叠

代码块的折叠，某些场景下非常必要。

本站通过代码块 meta#hidecode 的显式声明，让代码块初始默认为折叠收起状态。

使用风格：

```js:demo-code44.js hidecode
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
```

效果如下：

demo-code44.js

7. Diff 模式支持

rehype-prism-plus 插件初始提供了该功能支持。

使用风格：

```diff-js:demo-code55.js showLineNumbers
var num1, num2, sum;
- num1 = prompt("Enter number");
+ num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string
```

效果如下：

demo-code55.js
var num1, num2, sum;
- num1 = prompt("Enter number");
+ num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string

8. 锦上添花 - 模糊聚焦效果

（该效果的实现其实非常简单，同时对代码块功能点本身，实际只是锦上添花的存在。但是确实带给人耳目一新的效果，所以吾辈将其运用在了本站的代码块风格）

本站通过代码块 meta#focusBlur 的显式声明，来声明该代码块对包含高亮行声明的代码块使用定制的“模糊聚焦”效果。

核心 CSS 片段如下（类名已经具有很好的语义化，所以不再过多解释）

使用风格：

```scss focusBlur showLineNumbers
$duration: 0.35s;
pre.focus-blur-tag {
  & .code-line:not(.highlight-line) {
    // hl- 00
    transition: filter $duration, opacity $duration, background-color $duration;
    filter: blur(0.1rem);
    opacity: 0.5;
    // hl- 99
  }

  &:hover .code-line:not(.highlight-line) {
    // hl- 00
    filter: blur(0px);
    opacity: 1;
    // hl- 99
  }
}
```

效果如下：

$duration: 0.35s;
pre.focus-blur-tag {
  & .code-line:not(.highlight-line) {
    transition: filter $duration, opacity $duration, background-color $duration;
    filter: blur(0.1rem);
    opacity: 0.5;
  }

  &:hover .code-line:not(.highlight-line) {
    filter: blur(0px);
    opacity: 1;
  }
}

THX | 特别致谢: 模糊聚焦的效果灵感来源于开发者 janasundar 的个人博客， How to create apple music's background blur effect

语法汇总

语法效果其他注意事项
js:some-title.js声明标题
hl-11行间注释，声明下一行为高亮行
hl-00 & hl-99行间注释，声明指定范围的高亮行成对出现
showLineNumbers开启行号显示有高亮行情况下应开启此声明
focusBlur开启模糊聚焦效果有高亮行情况下才可选择开启此声明
maxH代码块最大高度限制
hidecode默认折叠收起代码块
diff-js支持 Diff 模式
{1,3-4}meta 元数据处声明高亮行废弃，请使用行间注释风格

完。

Md 文档代码块功能完备，以及自定义 meta 语法使用备忘

https://blog.ninoh.cc/loc-blog/1_code-block-feature-explore[Copy]
本文作者
ninohx96
创建/发布于
Published On
更新/发布于
Updated On
许可协议
CC BY-NC-SA 4.0

转载或引用本文时请遵守“署名-非商业性使用-相同方式共享 4.0 国际”许可协议，注明出处、不得用于商业用途！分发衍生作品时必须采用相同的许可协议。