---
title: 文档结构和配置
keywords: teedoc, 目录结构, teedoc 文档配置, teedoc 文档结构, teeodc sidebar
desc: teedoc， 将 markdown 或者 jupyter notbook 转换成 html 静态网页， 介绍了 teedoc 的基本使用， 包括文档结构和配置
---


## 构建与预览

在有`site_config.json`的文档目录下执行
```shell
teedoc serve
```

在显示 `Starting server at 0.0.0.0:2333 ....` 后，就可以了

打开浏览器访问: [http://127.0.0.1:2333](http://127.0.0.1:2333)


实时修改文件，保存文件后，默认过`3`秒后，会自动重新构建这个文件，然后浏览器会自动刷新
> 自动刷新的延迟时间可以设置，可以加 `-t` 参数， 比如`teedoc -t 0 serve`设置为`0`秒延迟，
> 另外也可以在文档配置中设置，见后面配置参数`rebuild_changes_delay`的说明


如果只需要构建生成`HTML`页面，只需要执行

```shell
teedoc build
```

>! 注意，如果是最终生成发布版本的文档， 一定要用`build`命令来生成网站页面，`serve`命令生成的页面只能用于本地预览，会有多余的预览相关的代码，不适合用在生产环境部署


另外，也可以指定参数`-d`或者`--dir` 来指定文档目录，这样就不用在文档目录下面执行命令了，比如
```shell
teedoc -d /home/teedoc/my_doc build
```


## 构建文档删除


构建好的文档会被放到`out`目录下，程序不会主动删除，如果需要清除，请手动删除



## 文档目录结构

```shell
├─.github
├─docs
│  ├─develop
│  │  ├─en
│  │  └─zh
│  └─get_started
│      ├─assets
│      ├─en
│      └─zh
├─pages
│  └─index
│      ├─en
│      └─zh
├─static
│
└─site_config.json
```

* `.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` 格式互相转换的命令

### 从 json 转到 yaml

```shell
teedoc -f ./config.json json2yaml
```

### 从 yaml 转到 json


```shell
teedoc -f ./config.yaml yaml2json
```


### 从 gitbook SUMMARY.md 转到 json


```shell
teedoc -f ./SUMMARY.md summary2json
```



### 从 gitbook SUMMARY.md 转到 yaml


```shell
teedoc -f ./SUMMARY.md summary2yaml
```




## site_config.json 网站配置

网站的配置项，比如网站名称，页面路由，插件配置等等

下面的示例配置文件看起来配置项比较多，不要被吓到，其实很简单，主要几个配置项，掌握了就思想就容易了

配置文件是`json`格式， 比如：

```json
{
    "site_name": "teedoc",
    "site_slogon": "happy to write",
    "site_root_url": "/",
    "site_domain": "teedoc.github.io",
    "site_protocol": "https",
    "config_template_dir": "./",
    "source": "https://github.com/teedoc/teedoc.github.io/blob/main",
    "route": {
        "docs": {
            "/get_started/zh/": "docs/get_started/zh",
            "/develop/zh/": "docs/develop/zh",
        },
        "pages": {
            "/": "pages/index/zh",
        },
        "assets": {
            "/static/": "static",
            "/get_started/assets/": "docs/get_started/assets"
        },
        "/blog/": "blog"
    },
    "translate": {
        "docs": {
            "/get_started/zh/": [ {
                    "url": "/get_started/en/",
                    "src": "docs/get_started/en"
                }
            ],
            "/develop/zh/": [ {
                    "url": "/develop/en/",
                    "src": "docs/develop/en"
                }
            ]
        },
        "pages": {
            "/": [ {
                    "url": "/en/",
                    "src": "pages/index/en"
                }
            ]
        }
    },
    "executable": {
        "python": "python3",
        "pip": "pip3"
    },
    "plugins": {
        "teedoc-plugin-markdown-parser":{
            "from": "pypi",
            "config": {
            }
        },
        "teedoc-plugin-theme-default":{
            "from": "pypi",
            "config": {
                "dark": true,
                "env":{
                    "main_color": "#4caf7d"
                },
                "css": "/static/css/custom.css",
                "js": "/static/js/custom.js"
            }
        }
    }
}

```

* `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`: 网页路由，包含了文档和页面以及资源文件的路由，比如文档的路由
```json
"docs": {
    "/get_started/zh/": "docs/get_started/zh",
    "/get_started/en/": "docs/get_started/en",
    "/develop/zh/": "docs/develop/zh",
    "/develop/en/": "docs/develop/en"
},
```
`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`提示没有翻译，更多详情请看[国际化 i18n](./i18n.md)
* `executable`: 可执行程序设置， 这里可以设置`python`和`pip`的可执行程序名，在安装插件时会用到
* `plugins`: 插件配置， 主要有名字， 来源， 配置项组成。
名字可以在[github](https://github.com) 搜索`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](./i18n.md#插件国际化)制作

## config.json 文档配置

这是针对每个文档的配置，放在每个文档的根目录， 比如`docs/get_started/zh/config.json`， 各个文档相互独立，可以设置一样的来保持网站导航栏一致

在这里面可以配置每个文档的导航栏， 以及页尾（`footer`）的内容, 也可以设置插件的`config`项，在当前文档会覆盖`site_config.json`中的配置，从而实现不同文档不同语言（国际化/i18n）或者样式等

比如：

```json
{
    "import": "config_zh",
    "id": "teedoc_page",
    "class": "language_zh",
    "locale": "zh-CN",
    "navbar": {
        "title": "teedoc",
        "logo": {
            "alt": "teedoc logo",
            "src": "/static/image/logo.png"
        },
        "home_url": "/",
        "items": [
            {
                "url": "/get_started/zh/",
                "label": "安装使用",
                "position": "left"
            },
            {
                "url": "/develop/zh/",
                "label": "开发",
                "position": "left"
            },
            {
                "url": "https://github.com/neutree/teedoc",
                "label": "github",
                "target": "_blank",
                "position": "right"
            },
            {
                "label": "语言: ",
                "position": "right",
                "type": "selection",
                "items": [
                    {
                        "url": "/get_started/zh/",
                        "label": "中文"
                    },
                    {
                        "url": "/get_started/en/",
                        "label": "English"
                    }
                ]
            }
        ]
    },
    "footer":{
        "top":[
            {
                "label": "链接",
                "items": [
                    {
                        "label": "使用 teedoc 构建",
                        "url": "https://github.com/neutree/teedoc",
                        "target": "_blank"
                    },
                    {
                        "label": "Copyright © 2021 Neucrack",
                        "url": "https://neucrack.com",
                        "target": "_blank"
                    }
                ]
            },
            {
                "label": "源码",
                "items": [
                    {
                        "label": "github",
                        "url": "https://github.com/neutree/teedoc",
                        "target": "_blank"
                    },
                    {
                        "label": "本网站源文件",
                        "url": "https://github.com/teedoc/teedoc.github.io",
                        "target": "_blank"
                    }
                ]
            }
        ],
        "bottom": [
            {
                "label": "*ICP备********号-1",
                "url": "https://beian.miit.gov.cn",
                "target": "_blank"
            },
            {
                "label": "*公网安备**************号",
                "url": "https://beian.miit.gov.cn/#/Integrated/index",
                "target": "_blank"
            }
        ]
    },
    "plugins": {
        "teedoc-plugin-search":{
            "config": {
                "search_hint": "搜索",
                "input_hint": "输入关键词，多关键词空格隔开",
                "loading_hint": "正在加载，请稍候。。。",
                "download_err_hint": "下载文件失败，请刷新重试或检查网络",
                "other_docs_result_hint": "来自其它文档的结果",
                "curr_doc_result_hint": "当前文档搜索结果"
            }
        }
    },
    "show_source": "编辑本页"
}
```
* `import`: 可以从模板文件导入配置，没有后缀的文件名。比如`site_config`中设置了`config_template_dir`为`./`，这里填`"import": "config_zh"`, 则代表从导入`site_config`同目录下的`config_zh.json`（优先）或者`config_zh.yaml`。
然后可以添加当前文档的配置，覆盖模板文件，同样的关键字，修改不同的内容即可，如果是数组(列表)，要替换模板文件的内容，需要在模板文件的数组项中增加`id`关键字，然后修改，如果不指定`id`关键字，则会追加到数组中。比如模板文件`config_zh`：
```json
{
    "locale": "zh-CN",
    "navbar": {
        "title": "teedoc",
        "items": [
            {
                "url": "/get_started/zh/",
                "label": "安装使用",
                "position": "left"
            },
            {
                "id": "language",
                "label": "Language: ",
                "position": "right",
                "items": [
                    {
                        "url": "/zh",
                        "label": "中文"
                    },
                    {
                        "url": "/en",
                        "label": "English"
                    }
                ]
            }
        ]
    }
}
```
具体某个文档的配置文件：
```json
{
    "import": "config_zh",
    "navbar": {
        "title": "teedoc123",
        "items": [
            {
                "id": "language",
                "label": "Language: ",
                "position": "right",
                "items": [
                    {
                        "url": "/get_started/zh",
                        "label": "中文"
                    },
                    {
                        "url": "/get_started/en",
                        "label": "English"
                    }
                ]
            }
        ]
    }
}
```
* `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`: 地域编号， 可以从[这里](https://www.science.co.il/language/Locale-codes.php)看到， 比如`zh`, `zh_CN`, `en_US`, `ja` 等。也可以通过程序`babel`获取
```
pip install babel
pybabel --list-locales
```
* `navbar`: 导航栏设置，每个文档都可以单独设置导航栏，要想保持整个网站统一，修改每个配置相同即可。关键字`type`用于第一层，用来表示导航栏的这个标签的类别，取值有：
  * `link`: 普通链接，不写`type`关键字时默认是这个选项
  * `list`: 有子项，会以下拉菜单的形式显示
![](../../assets/images/navbar.png)
  * `selection`: 单选项，比如选择语言。 不写`type`关键字并且有`items`关键字时，默认是这个选项
![](../../assets/images/navbar2.png)
  * `language`: 如果在 `site_config`中设置了`translate`, 则会自动将`language`类型的`items`填充为语言列表，这样就不用我们手动写语言列表了！ 效果和`selection`一样(其实内部代码就是将`language`类型自动替换为`selection`)
![](../../assets/images/navbar2.png)
* `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`， 则会在侧边栏中添加一个分类标记,效果如下：
![](../../assets/images/sidebar.png)

另外, 如果希望目录默认展开, 添加`"collapsed": false`即可

比如：
```yaml
items:
-   label: teedoc 简介
    file: README.md
-   label: 安装 teedoc
    file: install/README.md
-   label: 开始写文档
    file: usage/start.md
-   label: 插件
    file: plugins/README.md
    collapsed: false
    items:
    -   label: 主题插件
        file: plugins/themes.md
    -   label: 其它插件
        file: plugins/others.md
-   label: markdown 语法
    file: syntax/syntax_markdown.md
-   label: 使用了 teedoc 的网站
    file: usage/sites.md
-   label: 更多样例
    items:
    -   label: 二级子目录样例
        items:
        -   label: 三级子目录样例
            items:
            -   label: 文章1
                file: more/example_docs/doc1.md
        -   label: 文章2
            file: more/example_docs/doc2.md
    -   label: 这是一个链接
        url: https://github.com/teedoc/teedoc
        target: _blank
```

或者 `json` 格式

```json
{
    "items":[
        {
            "label": "teedoc 简介",
            "file": "README.md"
        },
        {
            "label": "安装 teedoc",
            "file": "install/README.md"
        },
        {
            "label": "开始写文档",
            "file": "usage/start.md"
        },
        {
            "label": "插件",
            "file": "plugins/README.md",
            "collapsed": false,
            "items":[
                {
                    "label": "主题插件",
                    "file": "plugins/themes.md"
                },
                {
                    "label": "其它插件",
                    "file": "plugins/others.md"
                }
            ]
        },
        {
            "label": "markdown 语法",
            "file": "syntax/syntax_markdown.md"
        },
        {
            "label": "使用了 teedoc 的网站",
            "file": "usage/sites.md"
        },
        {
            "label": "更多样例",
            "items":[
                {
                    "label": "二级子目录样例",
                    "items":[
                        {
                            "label": "三级子目录样例",
                            "items":[
                                {
                                    "label": "文章1",
                                    "file": "more/example_docs/doc1.md"
                                }
                            ]
                        },
                        {
                            "label": "文章2",
                            "file": "more/example_docs/doc2.md"
                        }
                    ]
                },
                {
                    "label": "这是一个链接",
                    "url": "https://github.com/teedoc/teedoc",
                    "target": "_blank"
                }
            ]
        }
    ]
}
```