# 介绍
# 什么是Teadocs？
Teadocs 是一款能够帮你快速构建html文档的工具，它基于nodejs编写，并使用markdown来编写文档内容。
Teadocs 提供内置的搜索技术，除了编写好你引以为豪的内容以外，你无需关注的任何额外的技术问题。
你可以使用它来编写开源书籍、API文档学习、笔记、学习心得、甚至可以用来写博客。
# 原理
Teadocs 会自动根据你编写的markdown文档自动生成html文档，并且生成的html文档具备可复用、可移植等特性，可以部署在任何你喜欢的地方。
# 安装
# installation
安装非常的简单，需要安装到全局中，方便随时通过shell调用。
需要nodejs版本 >= 8.0，npm 版本 > 3.
安装命令如下：
$ npm install -g teadocs
# 快速入门
# 安装它
需要nodejs版本 >= 8.0，npm 版本 > 3.
$ npm install -g teadocs
# 使用它
# 第一步
初始化一个文档项目
$ teadcos init mydocs
# 第二步
进入这个文档目录
$ cd mydocs
# 第三步
此步骤是进入文档编辑模式（开发模式），此模式将监视markdown文件的变化，实时热替换html页面。
$ teadocs dev
# 自动生成项目初始结构
如果你想偷懒，那么你可以在编写好tree.md（菜单的配置文件）的情况下，直接运行以下命令，teadocs可以自动帮你生成md文件。
$ teadocs init
# 编译成html
$ teadocs build
# 配置介绍
# 文档目录结构介绍
testdocs
├─ build #这个是编译输出的目录
│ ├─ config
│ │ ├─ main.html
│ │ ├─ nav.html
│ │ └─ structure.html
│ ├─ custom_theme.html
│ ├─ data.js
│ ├─ deploy.html
│ ├─ index.html
│ ├─ install.html
│ ├─ quick_start.html
│ ├─ static
│ │ ├─ css
│ │ ├─ font-awesome-4.7.0
│ │ ├─ fonts
│ │ ├─ images
│ │ └─ js
│ └─ template_markdown.html
├─ docs #这个是文档的源文件目录，也就是markdown文件目录。
│ ├─ config
│ │ ├─ main.md
│ │ ├─ nav.md
│ │ └─ structure.md
│ ├─ custom_theme.md
│ ├─ deploy.md
│ ├─ index.md
│ ├─ install.md
│ ├─ quick_start.md
│ └─ template_markdown.md
├─ static # 这个地方是用于存放文档中需要用要的静态文件，例如图片等，它会自动copy到build目录下。
|
├─ teadocs.config.js # 这是teadocs的主配置文件
└─ tree.html # 这是文档的菜单配置文件
# 主配置文件说明
菜单的配置文件是你文档根目录下面的 teadocs.config.js，它是一个javascript的文件。
主配置文件的所有配置项都不是必填你完全可以什么也不填写，它的代码如下：
'use strict';
const path = require('path')
module.exports = {
doc: {
name: "", //文档名称
description: "", //文档的描述
version: "", //文档的版本
dir: "", //文档的目录
outDir: "", //文档编译成html时输出的目录
staticDir: "" //文档所用到的静态文件的地址
},
theme: {
dir: "", //主题的目录，可自定义主题
title: "", //html的title标签
headHtml: "", //html head 的代码
footHtml: "", //html 底部 的代码
isMinify: true, //是否为输出的html启用压缩
rootPath: "/" //表示根路径，如果部署在深目录下面，这个配置项必填，不然会出现找不到资源路径的错误。
},
nav: {
tree: "./tree"
}
}
# 默认配置
module.exports = {
doc: {
name: "欢迎使用Teadocs文档生成系统",
description: "欢迎使用Teadocs文档生成系统",
version: "0.0.1",
dir: "./docs",
outDir: "./build",
staticDir: "./static"
},
theme: {
dir: __dirname + '/../themes/default',
title: "欢迎使用Teadocs文档生成系统",
headHtml: `
<meta name="description" content="欢迎使用Teadocs文档生成系统" />
<meta name="keywords" content="teadocs, 文档生成器" />
`,
footerHtml: "",
isMinify: false,
rootPath: "/"
},
nav: {
tree: "<ul><li><a>欢迎使用Teadocs文档生成系统</a></li></ul>"
}
}
# 菜单配置文件说明
菜单的配置文件是你文档根目录下面的 tree.md 文件，它采用了markdown语法来进行书写。
# 菜单结构
例如，本文档的菜单结构如下：
- [介绍](/index)
- [快速入门](/quick_start)
- [安装](/install)
- +配置介绍
- [文档目录结构介绍](/config/structure)
- [主配置文件说明](/config/main)
- [菜单配置文件说明](/config/nav)
- [markdown模版](/template_markdown)
- [自定义主题](/custom_theme)
- [部署](/deploy)
# 符号介绍
语法完全使用markdown里的无序列表定义语法，但是要特别注意以下几点：
-
[]里的内容表示菜单的标题，如果不写[]则代表这个菜单没有链接仅作为一个菜单名称。 -
()里的内容表示菜单的markdown文件的地址，并且也代表了生成后的html文件url。 -
+代表了在生成的html里默认展开这个菜单，需要注意的是，这不是markdown的语法，这是teadocs的规定，+一定要写在文本的前面，而不是[的前面。
# markdown模版
你编写的markdown文件可以使用内置的ejs模版引擎，比如我们可以轻而易举的写个循环，像这样：
< % [1,2,3,4].forEach(function () { % >
- 欢迎使用Teadocs文档生成工具
< % }) % >
效果：
<% [1,2,3,4].forEach(function () { %>
欢迎使用Teadocs文档生成工具
<% }) %>
# 自定义主题
你可以构建自己的主题文件，只要符合Teadocs的主题规范，具体可以自行参考默认主题。
# 如何使用自己构建的主题？
在 teadocs.config.js 文件的 theme.dir 配置项中指定你的自定义主题路径就可以了。
# 部署
# 上传到github
可以你的文档源文件上传到github上，使用 .gitignore 屏蔽 ./build 目录。
# 上传到服务器
建议使用nginx等静态服务器软件搭建一个静态服务器进行访问即可。
网友评论