一、真正决定一套 Markdown 资料能不能长期活下去的，往往不是语法，而是结构

很多人学习 Markdown 的第一阶段，注意力几乎全部放在语法本身上：标题怎么写，粗体怎么写，列表怎么写，代码块怎么写。这个阶段当然重要，因为如果连最基本的书写规则都不熟，文档根本不可能稳定产出。但当你真正开始积累资料以后，你会逐渐发现，决定一套文档能不能活得长、活得稳、活得像一套教材的，往往不是你会不会写井号和反引号，而是你有没有把文档放在一个合理的结构里。

这听起来像一句很普通的话，实际上分量非常重。因为一份 Markdown 文档本质上只是一个文本文件。文本文件本身并不神奇。它之所以强大，是因为它容易被搜索、容易被版本控制、容易被复制、容易被迁移、容易被不同工具读取。但这些优势只有在结构清楚的时候才会真正显现。如果一个仓库里到处都是 新建文档.md、笔记1.md、图片.png、最终版2.md 这样的文件名，图片散落在桌面、下载目录和聊天缓存里，那么就算你写的是 Markdown，这套资料也仍然会迅速失控。

所以，从这一章开始，我们暂时把注意力从“单篇文档怎样写”转移到“多篇文档如何组织”。对教材写作来说，这一步几乎是从写作者走向编者的分水岭。前者关心的是我今天能不能写出一篇文章，后者关心的是半年以后、换一台电脑以后、增加二十章以后、发到 GitHub 以后，这套内容是不是还清楚、还稳、还容易继续扩写。

二、目录结构不是装饰，它是在替未来的你做决定

很多初学者建立目录时，往往采用一种非常即时的思路：今天要写一篇文章，就在当前文件夹里新建一篇；明天又要写一篇，就再新建一篇；如果插图需要保存，就顺手拖到当前目录；如果暂时不知道放哪里，就先放桌面。短期看，这种方式阻力最小，因为它几乎不需要任何设计。但长期看，它会不断制造隐性成本。几周以后，你会开始忘记哪些文件是正文，哪些是草稿，哪些图片对应哪一章，哪些目录只是试验性的，哪些内容已经可以对外展示。

因此，目录结构要尽量在一开始就承担一种“预先约束”的功能。所谓预先约束，不是把你绑死在一个僵硬的体系里，而是替未来的自己减少混乱的可能。比如，如果你已经知道这个仓库是教材合集，而不是单篇文章集合，那么最自然的组织方式就不应该是把所有文档平铺在根目录，而应该先分出“分册”这一层。因为教材合集的核心单位不是“文件”，而是“册”。一旦这个基本单位确定，后面很多决策都会自然变简单：章节放哪里，研究资料放哪里，图片放哪里，根目录 README 应该承担什么作用，分册 README 应该承担什么作用，都会逐步变得明确。

目前这个仓库已经采用了这样一种思路：

• 根目录负责说明整个教材合集是什么。
• CATALOG.md 负责承担总目录导航。
• books/ 目录下面再按分册组织具体内容。

这样做的最大价值，不在于形式好看，而在于它把不同层级的责任切开了。根目录不再和某一门具体教材抢空间，分册目录也不需要承担整个仓库的总说明任务，章节文件则只需要专心解决章节本身的问题。

一个成熟的教材仓库，最好让任何第一次进入的人都能很快回答三个问题：

• 这个仓库整体是干什么的。
• 我现在看到的这一册讲什么。
• 如果我准备开始读，我应该从哪里进。

这三个问题如果能在目录和 README 结构里被自然回答，说明你的仓库已经具备了“可阅读”的基础，而不是只是“你自己勉强能认出来”。

三、为什么图片总是最先出问题

当一套 Markdown 资料刚刚开始时，图片问题往往不会立刻暴露。因为在非常早期，文件少、图也少，路径一时出错也不明显。但一旦内容开始增加，图片通常是第一个大面积暴雷的部分。原因很简单：文档是文本，本身比较稳定；而图片是外部资源，需要靠引用才能进到文档里。只要引用关系一乱，图片就会先坏。

Typora 官方的图片文档明确说明了这一点：Markdown 文件并不直接“拥有”图片，它只是引用图片。这个引用既可以指向网络地址，也可以指向本地路径。正因为如此，只要图片文件被移动、重命名、删除、同步丢失，或者路径写法不稳，文档中的图片就会断掉。很多人第一次看到这种情况时会觉得是软件坏了，其实更多时候是资源管理方式出了问题。

教材写作里，图片尤其重要。因为教材不是随便记两句笔记，它经常需要插入界面截图、目录示意图、代码结果图、流程图、对比图和操作截图。也就是说，图片在教材里不是偶尔出现的配角，而是很可能承担解释责任的核心素材。如果图片管理混乱，教材的可读性会被直接破坏。

因此，教材仓库中的图片不应该被当成“哪儿方便放哪儿”的附件，而应被视为正文的一部分。最稳妥的做法，通常是让图片目录和内容目录建立明确关系。例如，在当前这本《Typora 与 Markdown》中，就完全可以把图片统一放到 books/typora-and-markdown/images/ 下面，然后在章节里通过相对路径引用。这样做的好处很实际：你一眼就知道这些图片属于哪一册，而不是全仓混在一起；将来如果某一册需要整体迁移、发布、拆分，资源关系也不容易丢。

四、相对路径为什么是教材仓库的生命线

如果说目录结构解决的是“东西放哪里”，那么路径写法解决的就是“文档怎样找到这些东西”。而在一套需要长期维护、可能迁移、可能协作、可能发布到 GitHub 的教材仓库里，最值得优先建立的习惯之一，就是尽量使用相对路径。

GitHub 官方文档在说明仓库内文件和图片引用时，明确建议优先使用相对链接。原因并不抽象：相对链接跟仓库结构一起移动，只要结构没乱，链接就更有机会保持有效。绝对链接则完全不同。它往往绑定的是某个特定环境，比如你的本机目录、某个固定 URL、某个当前分支下的网页路径。你今天看着能用，不代表别人 clone 下来能用，也不代表你换个目录后还能用。

对初学者来说，最容易理解的一个例子就是图片。假设你在文档里写的是：

![示意图](/Users/mark/Desktop/temp/image.png)

这在你自己的当前机器上也许能显示，但对别人来说几乎一定是无效的。因为别人没有你的桌面目录，也没有这张图片。哪怕是你自己，过几天把桌面清理一下，这条链接也会立刻失效。相对路径则不同。如果图片被放在仓库内部的某个明确目录下，那么文档引用的就不是“你机器上的绝对位置”，而是“它和当前文档之间的相对关系”。而这种相对关系，只要目录不乱，就会稳定得多。

例如：

![第一章示意图](../images/chapter-01-figure-01.png)

这类写法的价值不只是技术层面的“路径更短”，而是它让文档跟仓库真正形成了一个整体。你把整个分册目录搬走也好，整个仓库推到 GitHub 也好，别人 clone 下来也好，只要相对位置关系保持不变，这张图就还能被找到。对教材工程来说，这几乎就是底层稳定性的来源之一。

五、Typora 在这里帮你的，不只是“插图更方便”

很多人提到 Typora 的图片功能时，只会想到一个非常表面的优点：拖一张图进去很方便。这个说法当然没错，但它太浅了。真正重要的是，Typora 提供了一套把图片插入行为逐步纳入工作流管理的能力。根据官方文档，Typora 可以在插入本地图片时选择不同策略，例如直接使用源路径、复制到指定目录、使用相对路径、在需要时配合 YAML Front Matter 设置图片根路径，甚至还能接入图片上传工具，把图片上传到云端图床。

对于教材仓库来说，其中最重要的不是所有高级功能，而是两件事：

• 插入图片时尽量复制到明确目录
• 生成尽可能稳定的相对路径

只要这两件事建立起来，Markdown 文档和图片资源之间的关系就会立刻稳很多。反过来，如果每次插图都只是“随手拖进去”，而不管 Typora 到底引用了哪里的原始文件，那么你写得越多，隐患就越多。

这里要特别提醒一点：云图床上传功能并不天然等于更高级。Typora 官方关于上传图片的文档里，专门给了非常明显的 warning，提醒用户注意第三方服务的隐私、可靠性、可删除性和法律风险。对教材仓库来说，除非你非常明确地知道自己的发布场景就是依赖图床，否则更保守也更稳妥的做法，通常仍然是先把图片放在仓库内部，和正文一起受版本控制。这种方式可能没有“到处都能外链”那么灵活，但它在可控性、可迁移性和可审计性上往往更适合教材项目。

六、从一开始就统一命名，会比后期大扫除省力得多

文件名和图片名看起来只是小事，实际上是最容易被低估的基础工程。因为命名一乱，搜索会变差，跳转会变差，图片引用会变差，章节管理也会变差。尤其是教材这种按章节长期增长的内容，一旦命名风格不统一，很快就会出现一种奇怪局面：内容明明都在，却越来越难管理。

教材仓库中的命名，最重要的不是“酷”，而是“稳定、可预测、可扩展”。从实际维护角度看，至少要尽量做到下面两点：

• 章节文件命名要有稳定编号：例如，章节文件如果从一开始就带编号，那么后续排序、导航、目录构建和导出都会自然很多。相反，如果今天写成“第一章”，明天写成“chapter2”，后天又写成“新版本第三章最终版”，那么任何自动化和人工管理都会越来越痛苦。
• 图片命名要和章节建立关系：与其把图片叫做 截图.png、新建图片 2.png、屏幕快照 2026-03-15.png，不如一开始就让它们和章节建立关系，比如 chapter-01-figure-01.png、chapter-01-figure-02.png。这种命名方式虽然没有那么“省事”，却在长期维护里非常值。因为它让你一眼就知道这张图属于哪一章，后续如果某张图失效、需要替换、需要统一压缩或重命名，都会轻松很多。

七、教材仓库的一个推荐起步结构

下面给出一个非常适合作为教材合集起步的结构范例。它不是唯一正确答案，但它足够稳，足够清楚，也很容易在后续扩写时继续长大。

textbook-collection/
├── README.md
├── CATALOG.md
└── books/
    ├── typora-and-markdown/
    │   ├── README.md
    │   ├── chapters/
    │   │   ├── 01-typora-and-markdown.md
    │   │   └── 02-structure-images-and-paths.md
    │   ├── images/
    │   └── research/
    └── another-book/
        ├── README.md
        ├── chapters/
        ├── images/
        └── research/

这个结构里，每一层都最好有自己的职责：

• 根目录负责解释“整个仓库是什么”。
• CATALOG.md 负责承担总导航。
• 分册 README 负责说明“这一册是讲什么的”。
• chapters/ 放正文。
• images/ 放图。
• research/ 放资料地图和研究性辅助文件。

这样做的一个大优点在于，即使某一册以后需要独立出去，它本身也已经具备了一个相对完整的小结构，而不是只能依附在当前仓库里勉强存在。

八、为什么研究资料也值得单独留目录

很多人会觉得研究资料不就是“自己查过的一些链接”吗，没必要专门放一个目录。但对教材型项目来说，研究资料的存在意义远不止备忘。它其实是在帮你回答两个问题：

• 正文背后到底依据了什么。
• 后续扩写时应该从哪里接着挖。

当一章内容越来越厚、主题越来越复杂时，很多判断已经不只是“我会不会”这么简单，而是涉及规范差异、平台行为、工具设置、版本变化和最佳实践。如果你没有把资料来源留下一点结构化痕迹，后面每次扩写都要重新到处找，既费时间，也容易把原来已经验证过的东西又搞乱。

现在这一册《Typora 与 Markdown》已经单独建立了 research/source-map.md。这就是一个很好的开始。它至少意味着，未来继续扩写时，不需要重新回忆“我上次到底查了哪些 Typora 官方文档”“哪些内容来自 Markdown Guide”“哪些判断需要回到 CommonMark 规范”。对教材工程来说，这类“研究痕迹”不是噪声，而是可持续性的组成部分。

九、把这一章真正落实到你自己的动作上

如果你准备把 Markdown 和 Typora 用作长期写作工具，那么这一章最重要的收获不应该只是“我知道了相对路径是什么”，而应该落实成几个具体动作：

• 先建目录，再写正文：不要把文章先随手写在某个临时位置，等写大了再补结构，因为后补结构的成本通常更高。
• 把图片视为正文资源的一部分：图片从插入那一刻开始，就应该知道自己要归档到哪里，而不是先随便放着，等出问题再想办法补救。
• 尽量让相对关系稳定下来：你要追求的不是“眼前能显示”，而是“换环境以后还能显示”。
• 把 README 和目录当成教材的一部分来写：教材不只是章节正文的集合，它还是一条阅读路径。README 和目录，决定了读者会不会顺利进入这条路径。

十、本章小结

这一章真正想说明的，其实只有一句话：Markdown 的强大，不只来自语法轻量，还来自结构稳定。一旦你准备写的不再是零散笔记，而是一套要长期维护、可能发布、可能扩展、可能协作的教材，那么目录结构、图片管理、相对路径、分册设计和研究资料留存，就都不再是边角问题，而是正文质量的一部分。

很多新手会觉得这些工作“像整理，不像写作”。但真正成熟的写作，恰恰包含这些整理。因为教材不是写给当下五分钟后的自己看的，而是写给未来几周、几个月、甚至几年后仍然要回来复用的人看的。你今天把结构搭稳一点，未来就能少付出很多混乱成本。这种收益，在 Markdown 世界里尤其明显。

参考资料

1. GitHub Docs, Basic writing and formatting syntax：https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
2. Typora Support, Images in Typora：https://support.typora.io/Images/
3. Typora Support, Upload Images：https://support.typora.io/Upload-Image/
4. Typora Support, YAML Front Matter：https://support.typora.io/YAML/
5. Markdown Guide, Hacks：https://www.markdownguide.org/hacks/