团队文档平台使用指南

欢迎使用本团队基于 Sphinx + Read the Docs (RTD) 构建的知识共享平台！
本平台旨在帮助组内成员方便地分享、维护和积累文档资料，包括论文写作笔记、技术博客、工具教程和学习资源等内容。

✅ 上传流程简要说明

你只需以下几步，即可将你的文档贡献到平台中：

  1. Fork 项目仓库

  2. 使用 Markdown 编写文档

  3. 上传文档至对应目录

  4. 提交 Pull Request（PR）

  5. 管理员审核合并

🪜 详细操作步骤

1️⃣ Fork 仓库

  • 打开平台项目主页。

  • 点击右上角 Fork，将项目复制到你自己的账号下（可以顺便点个star）。

2️⃣ 编写你的 Markdown 文档

  • 请使用 .md 格式（Markdown）撰写你的内容。

  • 每篇文档需包含一个清晰的一级标题，例如：

    # 如何使用 Pandoc 将 Markdown 转换为 PDF

本文将介绍如何使用 Pandoc 将 Markdown 文档转换为 PDF 文件……

  • 推荐使用 Typora 或 VS Code + Markdown 插件 进行编写。

3️⃣ 将文档添加到对应分类目录中

分类

说明

路径示例

论文写作

论文写作模板与经验

paper_writing/

论文笔记

阅读论文时的笔记与总结

paper_note/

技术博客

代码、框架、技术 等

tech_blog/

工具分享

工具类使用教程或技巧

tool_share/

资源分享

有价值的文档或在线资源

resource/

📌 注意：请尽量避免中文或特殊字符的文件名，建议用 下划线 + 英文 命名，如 transformer_primer.md

4️⃣ 提交 Pull Request

  • 将你修改后的内容 推送到你 fork 的仓库。

  • 打开原项目页面，点击 Pull Requests → New Pull Request。

  • 填写 PR 说明，简要描述你提交的内容（例如新增博客 / 更新某篇笔记）。

  • 等待管理员审核。

5️⃣ 等待合并 & 自动上线

  • 管理员合并 PR 后，Read the Docs 将自动构建你的更新。

  • 通常几分钟内即可在平台网站上看到更新内容。

✏️ 撰写建议

  • 请为每篇文档设置清晰的一级标题（# 开头），用于文档导航和目录展示。

  • 可使用 ##、### 设置子章节结构，利于阅读。

  • 支持数学公式（LaTeX）、图片、代码块等 Markdown 特性。

  • 若引用外部资源或文章，请注明来源。

🙋 常见问题

  • Q: Markdown 文件上传后没有显示在网页上？
    A: 请确保你的文档放在了正确目录，并包含一级标题（# 标题），否则不会被 Sphinx 收录。

  • Q: 构建失败怎么办？
    A: 检查 Markdown 是否有格式错误（如标题跳级），或联系管理员协助调试。

  • Q: 可以上传图片吗？
    A: 可以，请参考这篇文档：Markdown 文档插图指南（PicGo + 阿里云 OSS）。

📮 联系方式

如在使用过程中遇到问题，欢迎联系平台管理员或在项目中提 Issue。