文档结构和配置
一、构建与预览#
在有site_config.json
的文档目录下执行
在显示 Starting server at 0.0.0.0:2333 ....
后,就可以了
打开浏览器访问: http://127.0.0.1:2333
实时修改文件,保存文件后,默认过3
秒后,会自动重新构建这个文件,然后浏览器会自动刷新
自动刷新的延迟时间可以设置,可以加
-t
参数, 比如teedoc -t 0 serve
设置为0
秒延迟,
另外也可以在文档配置中设置,见后面配置参数rebuild_changes_delay
的说明
如果只需要构建生成HTML
页面,只需要执行
注意,如果是最终生成发布版本的文档, 一定要用
build
命令来生成网站页面,serve
命令生成的页面只能用于本地预览,会有多余的预览相关的代码,不适合用在生产环境部署
另外,也可以指定参数-d
或者--dir
来指定文档目录,这样就不用在文档目录下面执行命令了,比如
二、构建文档删除#
构建好的文档会被放到out
目录下,程序不会主动删除,如果需要清除,请手动删除
三、文档目录结构#
.github
: 自动构建脚本,在后面的章节将如何使用docs
: 文档,包含了多份文档, 每份文档都是单独一个文件夹pages
: 页面,包括主页、404页面等等页面static
: 静态文件文件夹,比如存放图片site_config.json
: 网站配置文件config.json
: 除了site_config.json
外,每个文档目录下都可以有config.json
用来配置文档相关页面sidebar.json
: 文档目录
在看如何使用配置文件之前, 一定要牢记, 配置文件很简单, 配置文件共只有两个文件名, 一个唯一的文档配置文件site_config
和 每个文档自己的配置文件config
四、配置文件#
配置文件可以是 json
或者 yaml
格式的文件,选择你喜欢使用的即可, 如果没接触过也不要害怕, 搜索一个教程花 10 分钟学习就能完全掌握。
如果你的文档目录内容很多,建议使用yaml
格式,看起来会更加简洁
teedoc
提供了 json
和 yaml
格式互相转换的命令
4.1. 从 json 转到 yaml#
4.2. 从 yaml 转到 json#
4.3. 从 gitbook SUMMARY.md 转到 json#
4.4. 从 gitbook SUMMARY.md 转到 yaml#
五、site_config.json 网站配置#
网站的配置项,比如网站名称,页面路由,插件配置等等
下面的示例配置文件看起来配置项比较多,不要被吓到,其实很简单,主要几个配置项,掌握了就思想就容易了
配置文件是json
格式, 比如:
site_name
: 网站名site_slogon
: 网站标语site_root_url
: 网站根目录路径, 使用默认值/
即可; 如果需要将生成的内容放到网站的文件夹中(不是根目录的文件夹),可以设置site_domain
: 网站域名,目前用到的地方:生成sitemap.xml
和robots.txt
site_protocol
: 网站协议,http
或者https
,目前用到的地方:生成sitemap.xml
和robots.txt
config_template_dir
:config
模板文件,其它文档目录的config.json
或者config.yaml
可以import
这里面的文件,默认位置为site_config
所在目录source
: 文档源码路径, 比如https://github.com/teedoc/teedoc.github.io/blob/main
,这里main
是文档主分支,会在文档页面添加Edit this page
按钮(链接),点击可跳转到对应文件源码。可以留空,则不添加链接。另外,可以在config.json
中添加"show_source": "编辑本页"
来定义按钮的文字内容为编辑本页
,如果希望文档没有这个按钮,则设置为"show_source": false
;也可在文件(md
或ipynb
文件)的头信息中添加show_source: 编辑本页
或者show_source: false
来设置route
: 网页路由,包含了文档和页面以及资源文件的路由,比如文档的路由
key
代表了最终生成的网站中文档的url
, 后面的值则是对应的源文档路径,
比如源文档docs/get_started/zh/README.md
,构建后会生成文件out/get_started/zh/index.html
, 如果不是md
文件(即不支持的文件),则会原封不动地拷贝文件,最后out
目录就是生成的网站
pages
同理,assets
则不会进行文档转换,直接拷贝到相应的目录
translate
: 翻译, 指定文档对应的翻译版本的url
和文件路径, 同样,在翻译版本的路径下需要有config
和sidebar
配置文件,并且config
文件中指定locale
来达到指定被翻译的文档语言, 比如中文可以是zh
,zh_CN
,zh_TW
, 英文是en
,en_US
等。翻译的sidebar
,以及文档路径需要和源文档一致,如果没有翻译可以不放翻译文件,用户访问没有翻译的页面时会跳转到no_tanslate.html
提示没有翻译,更多详情请看国际化 i18nexecutable
: 可执行程序设置, 这里可以设置python
和pip
的可执行程序名,在安装插件时会用到plugins
: 插件配置, 主要有名字, 来源, 配置项组成。
名字可以在github 搜索teedoc-plugin
来找到开源的插件,也欢迎你参与编写插件(只需要动 Python
语法即可);
from
字段填pypi
即可,如果插件下载到了本地也可以填写文件夹路径,也可以直接填git
路径比如git+https://github.com/*****/******.git
配置项则由具体的插件决定,比如teedoc-plugin-theme-default
就有dark
选项来选择是否启用暗黑主题
rebuild_changes_delay
: 检测到文件更改后,延迟多少秒自动重新生成该文档, 浏览器中会自动刷新页面,默认为3
秒,最短可以设置为0
秒, 可以使用teedoc -t 3 serve
或者teedoc --delay serve
来覆盖这个设置robots
: 自定义robots.txt
的内容, 比如"User-agent": "*"
代表允许所有客户端爬取, 这对SEO
会有影响。 比如不允许爬取JPEG
图片:"Disallow": "/.jpeg$"
, 不允许访问admin
目录:"Disallow": "/admin"
, 具体和robots.txt
的格式要求相同layout_root_dir
: 布局模板根目录, 默认为layout
, 即需要布局模板文件时会自动到这个文件夹下面寻找layout_i18n_dirs
:layout
的国际化翻译目录,可以是路径比如locales
,在某些特殊情况下也可以设置多个路径比如["locales1", "locales2]
。 文件内容可以参考i18n制作
六、config.json 文档配置#
这是针对每个文档的配置,放在每个文档的根目录, 比如docs/get_started/zh/config.json
, 各个文档相互独立,可以设置一样的来保持网站导航栏一致
在这里面可以配置每个文档的导航栏, 以及页尾(footer
)的内容, 也可以设置插件的config
项,在当前文档会覆盖site_config.json
中的配置,从而实现不同文档不同语言(国际化/i18n)或者样式等
比如:
import
: 可以从模板文件导入配置,没有后缀的文件名。比如site_config
中设置了config_template_dir
为./
,这里填"import": "config_zh"
, 则代表从导入site_config
同目录下的config_zh.json
(优先)或者config_zh.yaml
。
然后可以添加当前文档的配置,覆盖模板文件,同样的关键字,修改不同的内容即可,如果是数组(列表),要替换模板文件的内容,需要在模板文件的数组项中增加id
关键字,然后修改,如果不指定id
关键字,则会追加到数组中。比如模板文件config_zh
:
具体某个文档的配置文件:
id
: 文档的id
, 一般情况下不需要写,会将id
设置到config.json
目录下所有页面的<html>
标签上。 比如这里设置了teedoc_page
, 那么这个目录下所有页面都会变成<html id="teedoc_page"> ... </html>
。 如果markdown
文件设置了id
,则会覆盖这个值,即每个页面只能有一个id
。class
: 文档的class
, 一般情况下不需要写,会将class
设置到config.json
目录下所有页面的<html>
标签上, 多个class
用空格隔开。 比如这里设置了language_zh
, 那么这个目录下所有页面都会变成<html class="language_zh"> ... </html>
。 如果markdown
文件设置了class
,则会追加,比如config.json
中设置了language_zh
, 在README.md
中设置了class: zh_readme
, 则最终是class="language_zh zh_readme"
。 这个功能方便自定义每个页面的样式,或者不同文档的样式。locale
: 地域编号, 可以从这里看到, 比如zh
,zh_CN
,en_US
,ja
等。也可以通过程序babel
获取
navbar
: 导航栏设置,每个文档都可以单独设置导航栏,要想保持整个网站统一,修改每个配置相同即可。关键字type
用于第一层,用来表示导航栏的这个标签的类别,取值有:link
: 普通链接,不写type
关键字时默认是这个选项list
: 有子项,会以下拉菜单的形式显示
selection
: 单选项,比如选择语言。 不写type
关键字并且有items
关键字时,默认是这个选项
language
: 如果在site_config
中设置了translate
, 则会自动将language
类型的items
填充为语言列表,这样就不用我们手动写语言列表了! 效果和selection
一样(其实内部代码就是将language
类型自动替换为selection
)
footer
: 网站页脚,分为上下两个部分,上部又可以添加多个栏目,每个栏目里面可以有多个值plugins
: 配置插件的配置项,如果site_config.json
中已经设置了,会覆盖,即子config
的优先级更高show_source
: 在site_config.json
中设置了source
关键词的前提下,即文档源码路径, 比如https://github.com/teedoc/teedoc.github.io/blob/main
,这里main
是文档主分支,会在文档页面添加Edit this page
按钮(链接),点击可跳转到对应文件源码。设置"show_source": "编辑本页"
来定义按钮的文字内容为编辑本页
,不设置默认为Edit this page
, 如果希望文档没有这个按钮,则设置为"show_source": false
;也可在文件(md
或ipynb
文件)的头信息中添加show_source: 编辑本页
或者show_source: false
来设置
七、sidebar.json 文档目录(侧边栏)设置#
这里面设置文档的目录,每个文档一份,相互独立
文件路径使用相对路径,填文件名即可, README.md
会被自动转换成index.html
另外也可以不写file
路径,直接url
, 比如"url": "/get_started/zh/"
, 同时可以设置"target":"_blank"
在新窗口打开,不设置则在当前窗口打开
第一层 items
中的项目,如果只有label
,没有url
,file
和 items
, 则会在侧边栏中添加一个分类标记,效果如下:
另外, 如果希望目录默认展开, 添加"collapsed": false
即可
比如:
或者 json
格式
Gitalking ...