组织 Markdown 项目

为成功构建文档结构

良好的组织使 Markdown 项目更容易维护、浏览和扩展。无论您是管理软件项目的文档、一本书还是内容库，合理的结构都能节省时间并避免头疼。

本指南涵盖了组织 Markdown 文件和项目的最佳实践。

文件命名规范

使用描述性名称

根据文件内容命名，而不是使用随意的标识符：

# Good
getting-started.md
api-reference.md
troubleshooting-guide.md

# Avoid
doc1.md
chapter_final_v2_FINAL.md

小写加连字符

使用小写字母和连字符，确保跨系统兼容性：

# Good
user-authentication.md

# Avoid
User_Authentication.md

文件夹结构

文档项目

docs/
├── README.md
├── getting-started/
│   ├── installation.md
│   ├── configuration.md
│   └── quick-start.md
├── guides/
│   ├── user-guide.md
│   └── admin-guide.md
├── reference/
│   ├── api.md
│   └── cli.md
└── assets/
    └── images/

书籍或长篇内容

book/
├── README.md
├── 01-introduction/
│   ├── chapter.md
│   └── images/
├── 02-fundamentals/
│   ├── chapter.md
│   └── images/
└── appendix/
    └── glossary.md

最佳实践

一个文件一个主题

保持每个文件聚焦于单一主题。当内容不是埋在一个庞大的文档中时，更容易查找、编辑和复用。

使用根目录 README

在项目根目录创建一个 README.md，提供概述和到其他文档的导航。

资源文件单独存放

将图片和其他资源放在专用文件夹中。使用相对路径引用它们：

![Diagram](./assets/images/architecture.png)

索引文件

在较大的项目中，在每个文件夹添加索引或概述文件：

guides/
├── README.md  # Overview of all guides
├── user-guide.md
└── admin-guide.md

批量转换您的项目

版本控制技巧

.gitignore - 如果您会重新生成，则排除生成的文件（PDF、HTML）
有意义的提交 - 为文档更改编写清晰的提交信息
分支 - 为主要文档更新使用分支
Pull Request - 像审查代码一样审查文档更改

转换有组织的项目

组织良好的项目使批量转换变得简单：

导航到您的文档文件夹
选择需要转换的文件
使用批量转换处理所有文件
下载转换后的 ZIP 文件，保持您的结构