代码块与链接引用
你将学会什么
Section titled “你将学会什么”- 用带语言标注的代码块展示命令
- 复杂命令先写一句说明，再贴代码
- 区分内部路径链接与外部资源链接的写法
代码块和行内代码怎么分工？
Section titled “代码块和行内代码怎么分工？”课程作业和技术文档里，命令和代码是最容易被误写的地方。建议你这样做：
- 标明语言类型，方便高亮
- 只保留必要命令，不要截图整段终端
- 复杂命令先写一句话说明，再贴代码
# 安装依赖npm install# 启动项目npm run dev链接文案怎么写读者才愿意点？
Section titled “链接文案怎么写读者才愿意点？”不要默认认为所有人都和你用同一套环境，一句「在项目根目录执行」就能减少很多误解。链接也一样，关键是让读者知道点击后能得到什么，建议格式是：
- 内部路径说明当前页相对位置
- 外部链接说明资源类型，例如「官方文档」「参考实现」「课程要求」
不要只写「参考这里」，而要写「参考这里了解 API 设计约束」。信息越具体，读者越愿意点击。
代码块的语言标注同时决定高亮和可读性：bash、python 分别对应各自的语法高亮。标注错误会误导读者——把命令输出标成 bash，别人可能照着逐行执行。不确定语言时用 text 更稳妥。
行内代码与代码块的分工也值得明确：命令、参数、文件名这些会被原样复制的片段，用反引号包成行内代码（如 npm install）；多行命令或完整配置才用代码块。行内代码在句子里像「一个词」，代码块则是「一个可直接复制的单元」。README 的快速开始小节几乎只由这两种形态组成。
链接文案的通用规则是动词开头、点明结果：「安装依赖」「查看运行说明」「下载最新版本」。纯名词或模糊词（「这里」「文档」「点击」）无法让读者预判目标。README 内部链接优先用相对路径（docs/setup.md），仓库整体迁移后仍然可用；外部链接则保留完整 URL。
- CommonMark 规范——Markdown 的标准定义，代码块与链接语法的权威参考
- GitHub 文档：创建并高亮代码块——代码块语言标注的实际效果与示例
- npm 文档：npm install——正文示例命令的官方说明，含参数与使用场景
先自己回答，再看答案：
- 代码块为什么一定要标明语言类型？
- 什么时候应该先写一句说明再贴命令？
- 为什么「参考这里」这样的链接不够好？
参考答案
- 标明语言类型才能正确高亮，读者一眼能看出命令与输出的区别。
- 当命令依赖特定环境或位置（如「在项目根目录执行」）时，先说明能减少误解。
- 它没有告诉读者点击后能得到什么，信息不具体，读者不愿意点。
- 代码块标语言、只留必要命令，不要截图整段终端
- 先说明环境与位置，再贴命令
- 链接要写清「点了能得到什么」