代码块：长文中的‘荧光浮标’！让「关键内容」无损高亮呈现
本周为大家带来知识管理美学周刊的第005期
今日分享主题：如何在飞书文档等各大文档工具中，用好「代码块」组件？
（1）为什么需要代码块？
在日常的文档撰写中，我们经常需要呈现一些精确、结构化或带有技术性的关键信息。比如，一个核心的定义、一行重要的命令、一段配置代码，或者一个需要原样呈现的公式。
如果这些内容仅仅是加粗或斜体，它们很容易被淹没在普通文本中，既不显眼，也可能因为字体或排版问题而失去原有的格式。
比如像这样的👇🏻：
或者像这样的👇🏻：
这就好比在一面平整的墙上，你希望某个图案能浮雕般地凸显出来，而非仅仅是平面的印刷。通常来说，常规的强调方式往往无法满足这种需求。
因此，为了解决这个痛点，并达到内容“浮雕”般的效果，飞书文档的**“代码块”功能**，正是解决这一痛点的理想工具**。**
它能够将特定内容从常规文本流中给隔离出来，以一种更简洁有力的形式进行呈现，从而确保关键概念一眼可见，不被误读。
（2）代码块是什么？
接着，我们来聊聊：飞书文档的代码块是什么？
在「飞书文档」中，有一个组件叫代码块。代码块是一种特殊的格式化方式，它通常会以不同的背景色、固定宽度字体（等宽字体）以及保留原始缩进的方式来显示其中的文本，让你的文本，能够被框在一个区域里面。
这种独特的视觉样式，让代码块中的内容与周围的正文形成鲜明对比，如同一个独立的“信息框”。
（3）代码块什么时候使用？
代码块组件什么时候使用呢？
代码块的正确使用时机是：当你希望某些内容（比如代码片段、操作命令、精确定义等）能够原汁原味地呈现，并且在视觉上独立于正文、一眼就能被识别时，就可以使用代码块组件。
简单来说，它不是用来给普通的句子或段落做强调的，如果只需要简单的强调，那么我们用前面提到的五种强调方式就可以。而对于代码块组件来说，可以理解为是专门为那些需要被精确「展示」或「引用」的特定信息而设计的。
（4）3大场景范例解读
知道了什么时候使用代码块组件，下面用几个场景范例来辅助大家进一步上手该组件。
第一种：「核心定义」场景
场景解读：将需要精确理解的核心概念、术语定义或者关键原则放入代码块。
适用场景：
具体示例：
①产品文档中的专业术语定义
比如当你在撰写产品文档，需要向用户或团队成员解释一个专有名词时，使用代码块可以让定义清晰突出，不易混淆。
②项目规范中的核心原则声明
在项目启动或团队协作中，一些核心原则或约定需要被所有人明确理解和遵守。将它们放入代码块，能强化其重要性和不可更改性。
③学习笔记中的重要公式或定理
在个人或团队的学习笔记中，对于那些需要精确记忆和引用的公式、定理或代码片段，代码块是最佳的选择。比如说，你想要给大家普及墨菲定律，那么你就可以把它框在一个代码块里面，这样大家就会聚焦在这个框里面，去了解到「墨菲定律」是什么内容。
第二种：「操作指令集」场景
概念：呈现需要用户精确输入或执行的命令、快捷键组合或操作路径。
适用场景：
具体示例：
①软件使用教程中的命令行指令
当你在编写软件开发或系统操作的教程时，这个时候需要用到的命令行指令可能必须精确无误，且格式不能被破坏。此时，你可以用代码块来承载这些指令，确保用户可以轻松复制粘贴。
②系统配置指南中的参数设置
当你在给别人提供系统或应用配置的指导时，参数名称、值和格式的准确性至关重要。代码块能清晰地展示这些配置项，避免因为格式错误导致的问题。
③日常操作中的键盘快捷键
为了帮助用户提高效率，清晰地展示键盘快捷键组合非常重要。那代码块组件也能让这些快捷键组合更加醒目，方便用户记忆和使用。比如我们用代码块来插入飞书文档的快捷键指令：
第三种：「结构化数据窗」场景
概念：展示JSON、YAML、XML等结构化数据，或伪代码、算法步骤等。
适用场景：
具体示例：
①API文档中的请求/响应示例
在编写API文档时，我们通常需要对请求体、响应体或错误码的JSON/XML结构，进行精确展示，而代码块组件就能完美地保留这些结构的格式和层级。
②配置文件中的参数结构
有时候，我们需要展示复杂的配置文件结构如YAML、INI等），那代码块组件能确保缩进和层级关系的正确性，避免因格式错误导致的配置失败。来看下面YAML格式的代码：
③算法设计中的伪代码逻辑
在设计算法或描述复杂逻辑流程时，使用伪代码（Pseudocode）能清晰地表达步骤和条件，而代码块能保持其结构化和可读性。
比如我们在云中江树老师的结构化提示词知识库，随机抽取一篇Mardown语法的提示词：
*提示词来源地址：*https://langgptai.feishu.cn/wiki/ASXOwDbTEiH9CUkXFA5cLHumn88?from=from_copylink
以上就是对3大场景、9大示例的详细介绍。在平常使用时，你可以根据具体的内容类型，来灵活运用。
（5）如何在「飞书文档」中，唤起代码块组件
最后一步，已经知道了在什么场景下用代码块组件，现在就是要知道怎么在文档里面，唤起代码块组件了。
我们来看看，在飞书文档里面，如何快速使用代码块组件？
输入快捷指令：在文档中新起一行，输入/，然后输入代码块，选择弹出的“代码块”选项。
粘贴或输入内容：将你想要放入代码块的内容粘贴进去，或者直接在代码块内输入。
选择语言（可选但推荐）：在代码块的右上角，你可以点击下拉菜单，选择对应的编程语言（如 JavaScript, Python, JSON, Plain Text 等）。选择后，飞书会自动进行语法高亮，让代码更易读。
调整大小与位置：代码块会根据内容自动调整高度，当然你也可以像操作其他内容块一样，拖拽它在文档中的位置。
md语法唤起组件：除此之外，你还可以通过 ````+代码语言+空格` 这样的markdown语法，来唤起这个组件。
快捷键唤起组件：除此之外，还可以通过cmd + option + C，来直接把文本转换为代码块组件。
ok，到这里，关于整个代码块组件的讲解，就到尾声了~
通过「代码块组件」这种方式，能让你的关键概念、指令和数据，以一种更清晰、专业且不易混淆的形式呈现，极大程度地提升了文档的可读性与准确性，让读者或者用户自己在长文文档中，也能迅速地捕捉到最重要的“浮标”！
以上就是本期分享的全部内容，我们下期见🍻🍻🍻