teedoc 快速开始

本篇文档主要是为了让刚接触的你快速上手，更多请看后面更详细的文档

安装 Python3

teedoc 是基于Python3语言开发的软件，需要有这个软件的支持

比如在Ubuntu上：

sudo apt install python3 python3-pip git

Windows 和 macOS请到官网下载

安装 teedoc

打开终端(Windows按Ctrl+R输入cmd)，输入：

pip3 install teedoc

以后使用以下命令来更新软件

使用前务必同时更新软件和插件再使用，以防版本不同导致出现问题

pip3 install -U teedoc

如果你的网络使用 pypi.org 速度很慢，可以选择其它源，比如清华 tuna 源： pip3 install teedoc -i https://pypi.tuna.tsinghua.edu.cn/simple

现在你可以在终端使用 teedoc 命令了

如果不能，请检查是不是Python可执行目录没有加入到环境变量 PATH,
比如可能在 ~/.local/bin

新建工程

新建一个空目录用来放文档工程

mkdir my_site
cd my_site
teedoc init

或者

teedoc -d my_site init

选择1，也就是minimal模板进行生成，也可以直接teedoc -d my_site --template=minimal init进行生成

这会在 my_site 目录下自动生成一些基础文件

另外，除了使用init命令生成一份最小工程，你也可以获得一份官网文档源码，基于这个文档内容修改

git clone https://github.com/teedoc/teedoc.github.io my_site

或者

git clone https://gitee.com/teedoc/teedoc.gitee.io my_site

安装插件

这会根据site_config.json中的plugins的插件设置安装插件

cd my_site
teedoc install

插件也是以 python 包的形式发布的，所以这会从 pypi.org 下载对应的插件，同样，也可以使用其它源，比如清华 tuna 源： teedoc -i https://pypi.tuna.tsinghua.edu.cn/simple install

使用前务必同时更新软件和插件再使用，以防版本不同导致出现问题

构建 `HTML` 页面并起一个`HTTP`服务

teedoc serve

这个命令会先构建所有HTML页面以及拷贝资源文件，然后起一个HTTP服务
如果只需要生成页面，使用

teedoc build

在显示 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即标题，更多配置项和文档格式请阅读文档

---
title: title
---

## 标题一

内容一

## 标题二

内容二

如果没有元数据区，则至少需要一个一级标题作为文章标题，比如：

# 文章标题

## 标题一

内容一

或者

文章标题
===

## 标题一

内容一

在 sidebar.yaml 中添加侧边栏链接

items:
-   label: Brief
    file: README.md
-   label: First
    file: first.md

使用图片

在.md文件中使用图片，有三种方法：

直接引用 url，比如 https://teedoc.github.io/static/image/logo.png 或者 /static/image/logo.png
相对路径引用图片文件。比如 ./assets/logo.png. 比如

doc1
├── assets
     └── logo.png
├── config.json
├── README.md
└── sidebar.yaml

这是工程中的一份文档，下面有config配置文件和sidebar文件.
直接在README.md文件中引用![logo](./assets/logo.png) 即可。
需要注意的是，只能引用当前文档内文件夹的图片，不能用相对路径引用这份文档以外的图片

如果需要引用当前这份文档之外的路径的资源，可以通过设置路径映射（route）实现，比如在docs目录下有文件：

docs
└── assets
     └── logo.png
      doc1
      ├── config.json
      ├── README.md
      └── sidebar.yaml
static

我们在README.md文件中引用![logo](../assets/logo.png) ，会发现图片没法显示

要让这种引用能够使用，需要在site_config中设置

"route": {
    "docs": {
        "/doc1/": "docs/doc1"
    },
    "assets": {
        "/static/": "static",
        "/assets/": "docs/assets"
    }
}

这样设置就可以使用了。

原因是：我们设置了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