- 作者:
- 分类:项目&制作->开源项目
- 阅读:2811
- 点赞:22
- 版权:CC BY-SA 4.0
- 创建:2021-02-03
- 更新:2022-09-20
原文链接(持续更新):https://neucrack.com/p/342
效果和文档/使用方法(官网): teedoc.neucrack.com 或者 teedoc.github.io
软件源码: https://github.com/neutree/teedoc (欢迎 star)
文档源文件: github.com/teedoc/teedoc.github.io
一款用 Python 写的开源静态文档网站生成/静态文档页面生成工具,支持从 Markdown 或者 jupyter notebook 转换成 HTML,支持多文档,多语言,支持自定义页面, SEO友好等功能,无需使用数据库,轻量稳定实用。
以下场景可使用teedoc
:
- 建文档网站,并且最好支持放多份文档,和自定义页面
- 建
WiKi
网站 - 建个人或者企业知识库
- 建个人或者企业网站
其实已经有很多类似的工具了, read the docs
, docusaurus
,docsify
,gitbook
等等
之前自己用的gitbook
, 但是官方不维护了, 虽然市面上挺多现成的工具的,要趁手,还是自己手撸的好,于是就造了个轮子,相比 gitbook
, 支持多线程构建,更好的多文档管理,SEO更友好(方便搜索引擎收录网站),最重要的是,有活人更新!
另外,使用了 Python
作为开发语言,足够简单易用,要做自定义也很简单, 前端也只用了一个jquery
,没有其它复杂的框架,相信很多开发者都有能力基于这个进行自定义开发,另外也支持插件哦~
因为自己和公司都常年有文档公开需求,会长期维护~ 欢迎测试使用, 欢迎给项目一个star,你的 star 就是我维护的动力!!!
有任何疑问, 可以来查找或者提交issue (提交 issue 需要先登录 github), 有特殊需求也可以在首页联系到我
特性
- 使用简单, 跨平台,只依赖
Python3
- 不需要数据库,网站全静态页面
- 部署简单, 生成的网站是全静态页面,直接拷贝到服务器或者上传到三方机构即可部署
- 书写简单,使用 Markdown 语法编写
- Jupyter notebook 支持
- HTML 支持,可直接使用 HTML 编写页面,自由度大
- 多文档支持
- 插件支持
- 多主题支持(由插件实现)
- 通过 css 控制精确到页的样式(通过自定义每页的 id 和 class 实现)
- 多级目录支持(无穷级)
- 多语言支持(手动翻译)(国际化/i18n)
- 多语言支持(翻译插件)
- 多版本支持(实现方法同多语言)
- 搜索支持
- SEO 友好
- 实时预览更改
- 并行构建,更快的构建速度
- 博客支持
- gitbook 切换过来友好, 只需要设置好
route
和使用命令(summary2yaml
)转换目录文件(SUMMARY.md
)即可 - 评论(插件), 比如
gitalk
本地使用方法
看文档: teedoc.neucrack.com 或者 https://teedoc.github.io/
如果你已经有 Python 环境,只需要(没有python环境则需要先下载安装):
- 安装 teedoc
pip3 install teedoc
- 获取模板源码
git clone https://github.com/teedoc/teedoc.github.io my_site
或者
git clone https://gitee.com/teedoc/teedoc.gitee.io my_site
也可以克隆另外一个模板仓库github.com/teedoc/template
- 安装插件
cd my_site
teedoc install
- 本地预览
teedoc serve
如果要部署的文件,请使用
teedoc build
命令,serve
命令会有跟预览相关的多余的文件
使用 github pages 基于 teedoc 快速创建网站
使用 teedoc 官网模板, 使用 github pages 功能, 可以快速创建一个属于你自己的网站, 不需要自己搭建和维护服务器, 不需要自己部署 HTTPS 证书, 也不需要任何密钥配置, 3 分钟内就可以完成.
不过 github pages 服务也有缺点, 就是国内某些网络线路可能访问速度比较慢,也可能无法访问(不过自定义域名能解决一部分问题)
访问 teedoc.github.io 或者 template(模板仓库,内容更少) 仓库, 点击
Use this template
设置新仓库的名字为
用户名或者组织名.github.io
, 选择公开仓库, 然后确认提交等待自动构建生成新的分支
gh-pages
, 可以点击Actions
栏目查看自动构建的进度, 如果有绿色的勾勾出现了就代表可以了, 如果出现了红色的叉叉则是构建失败了, 哪里出了什么问题, 可以按照下面的截图方法点进去查看日志(提交问题必须要日志截图)并提交 issue 反馈, 如果着急可以在本网站首页给我发消息询问
如果有错误, 可以按照下图点进去查看错误日志:
设置仓库的
pages
服务, 选择gh-pages
分支, 如果没有这个分支, 则是上一步还没进行完或者出错了,可以查看问题提交 issue 反馈然后访问
用户名或者组织名.github.io
, 就会发现有网页啦, 内容和teedoc.github.io
的一模一样!可以自定义域名,创建
pages/index/zh/CNAME
文件,注意不需要后缀名, 然后写入自定义的域名,提交代码即可