开源静态文档网站生成工具 teedoc

官网: teedoc.neucrack.comteedoc.github.io
本文档源文件: github.com/teedoc/teedoc.github.io
源码: https://github.com/teedoc/teedoc 如果你喜欢这个项目,请务必登录 github 给项目点个 star

Markdown 或者 Jupyter Notebook 格式的文档转换为 HTML 静态网页

以下场景可使用teedoc

  • 建文档网站,并且最好支持放多份文档(比如你有一本叫Python学习C++学习两本书,它们都有单独的目录, teedoc则是书库)
  • 文档和网页页面共存,支持自定义HTML页面
  • WiKi网站
  • 建个人或者企业知识库
  • 建个人或者企业网站
  • 博客

如果你在使用过程中遇到了问题, 可以在这里 (需要先注册并登录 github) 寻找相似问题, 或者创建 issue

也可以加 QQ群 566531359 讨论

特性

  • 多文档支持, 将多种文档和网页放到同一个站点
  • 使用简单, 跨平台,只依赖 Python3
  • 不需要数据库,网站全静态页面
  • 部署简单, 生成的网站是全静态页面,直接拷贝到服务器或者上传到三方机构即可部署
  • 书写简单,使用 Markdown 语法编写
  • Jupyter notebook 支持
  • HTML 支持,可直接使用 HTML 编写页面,自由度大
  • 插件支持
  • 多主题支持(由插件实现)
  • 通过 css 控制精确到页的样式(通过自定义每页的 id 和 class 实现)
  • 多级目录支持(无穷级)
  • 多语言支持(手动翻译)(国际化/i18n)
  • 多语言支持(翻译插件)
  • 多版本支持(实现方法同多语言)
  • 搜索支持
  • SEO 友好
  • 实时预览更改
  • 并行构建,更快的构建速度
  • 博客支持
  • gitbook 切换过来友好, 只需要设置好 route 和使用命令(summary2yaml)转换目录文件(SUMMARY.md)即可
  • 评论(插件), 比如 gitalk

演示

本网站即采用 teedoc 生成,你现在看到的就是生成后的网站的样子。

另外还有其它网站使用了teedoc,具体请看这里

类似的工具

实际上这种类型的工具已经有很多了,但是每一个又稍微不同,按照自己的需求选择一个就好了

如果你有选择困难症,那么符合以下部分条件,都建议使用 teedoc:

  • 用来做文档网站? 手里有很多文档网站,希望将他们统一到一个站点?还各种语言的网站? 用 teedoc
  • 使用 Jupyter notebook 写文档或代码? 果断选择 teedoc
  • 功能符合你的需求吗?
  • 界面符合你的审美吗(可以自定义 css, 或者换主题插件)
  • Python 熟悉? 可以随时自定义插件和功能

其它类似工具:

  • docusaurus: teedocUI 布局几乎和它类似,不过它使用 vue 写的, teedoc 是原生 js, 如果你用的是 vue 可以考虑用这个
  • gitbook: 曾经很好用的工具,但是官方不维护了,转向商业了,不建议再使用
  • docsify: 只需要一个页面,markdown 在浏览器渲染,而不是预先渲染成 HTML, 好处就是轻量,但是 SEO 不太友好,可以用它的 SSR 功能, nodejs 编写
  • readthedocs(Sphinx): 其实是用了用 Sphinx 做为生成工具,Python 官网文档就是这个工具生成的, 很多开源项目使用的工具,readthedocs 只是一个公开文档的网站,你不用自己搭建网站,注册登录就可以开始写文档,对 RST 格式支持友好
  • mkdoc: 也是一个 python 写的工具,简单易上手,插件也多,如果你的文档是单一语言的文档,可以使用这个工具

一些使用建议

  • 在 footer 添加 使用 teedoc 生成, 帮助更多人发现 teedoc,促进项目的成长
  • 使用模板项目开始一个新的文档项目,可以先跑起来,然后再根据自己的需求修改,这样上手更快哦

快速开始

查看快速开始来安装并使用吧!