编写文档内容

放在文档目录下面的文件,如果是可是识别的文件,比如*.md, 则会转换成*.html, 如果不能识别,比如*.jpg, 则会原封不动地拷贝到输出文件夹(out

Markdown 解析由插件teedoc-plugin-markdown-parser完成, 模板工程默认使用了该插件。 jupyter-notebook插件teedoc-plugin-jupyter-notebook-parser默认可能没有使用, 需要在site_config文件中配置

使用 Markdown 编写文档

  • 在文档目录(包含了config.json或者config.yaml配置文件的目录)下创建一个.md格式的文件(可以随便建立子目录),使用UTF-8文件格式(尽量不要使用Windows默认的记事本, 推荐使用vscode + 一款markdown插件, 或者其它Markdown编辑器比如typora, 或者纯文本编辑器notepad++
  • 给文件添加头内容(metadata), 至少需要title键值, 比如:
---
title: markdown 语法
tags: teedoc, markdown, 语法
keywords: teedoc, markdown, 语法
desc: teedoc 的 markdown 语法介绍和实例
---
  • 查看Markdown 语法了解更多使用Markdown编写文档的语法和细节, 如果你使用过Markdown, 也强烈建议花 2 分钟浏览一遍!
  • 如果你需要将文档链接到左侧目录, 则在sidebar.json或者sidebar.yaml中配置

使用Jupyter notebook 文件

需要插件teedoc-plugin-jupyter-notebook-parser, 默认可能没有使用, 需要在site_config文件中配置。

然后复制.ipynb格式的文件到文档目录即可, 具体的样例见Jupyter 语法

链接、图片等资源文件

资源文件会被拷贝到输出文件夹(out), 所以最重要的是怎么在文档中引用

最简单和推荐的方法

使用相对路径:

资源文件可以放在文档对应的目录,比如文档docs/get_started/zh, 可以创建docs/get_started/zh/assets/images/logo.png, 然后在docs/get_started/zh/README.md中使用相对路径引用,即![](assets/images/logo.png)

进阶方法

这种情况适用于多份文档都引用同一个文件夹下(url)的资源, 方便维护多份文档,比如多语言翻译,或者减少 CDN 流量消耗

使用文档路径外的资源,在site_config.json 中配置

{
    "route": {
        "docs": {
            "/get_started/zh/": "docs/get_started/zh",
        },
        "assets": {
            "/get_started/assets/": "docs/get_started/assets"
        }
    }
}

这个设置会将docs/get_started/assets整个目录拷贝为/get_started/assets
所以只需要在docs/get_started/zh/README.md中使用相对路径引用,即![](../assets/images/logo.png)