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 国际”许可协议,注明出处、不得用于商业用途!分发衍生作品时必须采用相同的许可协议。