teedoc 快速开始
本篇文档主要是为了让刚接触的你快速上手, 更多请看后面更详细的文档
一、安装 Python3#
teedoc
是基于Python3
语言开发的软件,需要有这个软件的支持
比如在Ubuntu
上:
Windows
和 macOS
请到官网下载
二、安装 teedoc#
打开终端(Windows
按Ctrl+R
输入cmd
),输入:
以后使用以下命令来更新软件
使用前务必同时更新软件和插件再使用,以防版本不同导致出现问题
如果你的网络使用
pypi.org
速度很慢,可以选择其它源,比如清华 tuna 源:pip3 install teedoc -i https://pypi.tuna.tsinghua.edu.cn/simple
现在你可以在终端使用 teedoc
命令了
如果不能,请检查是不是Python
可执行目录没有加入到环境变量 PATH
,
比如可能在 ~/.local/bin
三、新建工程#
新建一个空目录用来放文档工程
或者
选择1
,也就是minimal
模板进行生成, 也可以直接teedoc -d my_site --template=minimal init
进行生成
这会在 my_site
目录下自动生成一些基础文件
另外,除了使用init
命令生成一份最小工程,你也可以获得一份官网文档源码,基于这个文档内容修改
或者
四、安装插件#
这会根据site_config.json
中的plugins
的插件设置安装插件
插件也是以
python
包的形式发布的, 所以这会从pypi.org
下载对应的插件,同样,也可以使用其它源,比如清华 tuna 源:teedoc -i https://pypi.tuna.tsinghua.edu.cn/simple install
使用前务必同时更新软件和插件再使用,以防版本不同导致出现问题
五、构建 HTML
页面并起一个HTTP
服务#
这个命令会先构建所有HTML
页面以及拷贝资源文件,然后起一个HTTP
服务
如果只需要生成页面,使用
在显示 Starting server at 0.0.0.0:2333 ....
后,就可以了
打开浏览器访问: http://127.0.0.1:2333
同时可以看到目录下多了一个out
目录,里面就是生成的静态网站内容,直接拷贝到服务器使用nginx
或者apache
进行部署即可
六、文档结构#
因为 teedoc
特别为 多文档系统 设计, 有个基本概念, 每个文档工程包含了多份文档, 每份文档都有自己的配置文件名为 config 需要先牢记
工程里面有几个重要文件:
- 工程根目录有
site_config.json
文件, 是工程的主要配置 - 工程里面可以有多份文档,在
site_config
的route
配置项中设置,每份文档目录下面必须有config.json
和sidebar.json
(json
文件也可以是yaml
文件),config
文件负责这份文档的配置项,比如文档名称,多份文档可以使用import
公用一份模板
七、添加一篇文档#
- 在本文件所在目录创建
markdown
(以.md
结尾的)文件,比如first.md
,添加内容
注意每份文档下的
README.md
会被自动转成index.html
页面,也可以改成index.html
使用html
语法编写,README.md
和index.html
必须至少有一个。否则访问文档会出现404
错误。
每篇文章开头都可以有一个元数据区
, 用以配置文章的相关配置, 至少需要一个title
即标题,更多配置项和文档格式请阅读文档
如果没有元数据区
,则至少需要一个一级标题作为文章标题,比如:
或者
- 在
sidebar.yaml
中添加侧边栏链接
八、使用图片#
在.md
文件中使用图片,有三种方法:
直接引用
url
, 比如https://teedoc.github.io/static/image/logo.png
或者/static/image/logo.png
相对路径引用图片文件。 比如
./assets/logo.png
. 比如
这是工程中的一份文档,下面有config
配置文件和sidebar
文件.
直接在README.md
文件中引用![logo](./assets/logo.png)
即可。
需要注意的是, 只能引用当前文档内文件夹的图片,不能用相对路径引用这份文档以外的图片
- 如果需要引用当前这份文档之外的路径的资源,可以通过设置路径映射(
route
)实现,比如在docs
目录下有文件:
我们在README.md
文件中引用![logo](../assets/logo.png)
,会发现图片没法显示
要让这种引用能够使用, 需要在site_config
中设置
这样设置就可以使用了。
原因是: 我们设置了
docs/doc1
下的文档渲染后拷贝到out/doc1
目录,docs/assets
拷贝到out/assets
,所以在out/doc1
下面的文档直接使用相对路径就可以引用out/assets
目录的资源文件了
九、设置地区#
设置文档地区,以让某些页面和文字显示为对应的语言, 比如搜索插件会根据文档地区生成对应的搜索提示等
在config/config.json
文件中,修改"locale": "en"
为实际使用的地区, 比如zh
, zh_CN
, zh_TW
, en_US
, ja
等, 更多看i18n文档
十、更多例子#
更多请访问: teedoc.neucrack.com 或者 teedoc.github.io
更多例子访问: github.com/teedoc/teedoc.github.io 或者 https://github.com/teedoc/template , 或 sipeed wiki
Be the first person to leave a comment!