teadocs文档工具的使用

一、介绍

什么是Teadocs？

Teadocs 是一款能够帮你快速构建html文档的工具，它基于nodejs编写，并使用markdown来编写文档内容。

Teadocs 提供内置的搜索技术，除了编写好你引以为豪的内容以外，你无需关注的任何额外的技术问题。

你可以使用它来编写开源书籍、API文档学习、笔记、学习心得、甚至可以用来写博客。

原理

Teadocs 会自动根据你编写的markdown文档自动生成html文档，并且生成的html文档具备可复用、可移植等特性，可以部署在任何你喜欢的地方。

二、快速入门

安装它

需要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

三、安装

installation

安装非常的简单，需要安装到全局中，方便随时通过shell调用。

需要nodejs版本 >= 8.0，npm 版本 > 3.

安装命令如下：

$ npm install -g teadocs

四、文档目录结构介绍

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等静态服务器软件搭建一个静态服务器进行访问即可。

运行项目结果

teadocs dev

默认端口号是3210

源文件

源文件修改完，html是事实自动生成的，只需要在浏览器中刷新下即可。
小伙伴是不是很简单呢，看完了赶紧试试吧，熟能生巧。

我是你们的博主，入行三年的程序猿(入行久久，未逢敌手)，

喜欢折腾代码的加群（群号:822286811）一起交流学习【python、VBA、Shell、Linux、dos、爬虫、拆机、装系统技术交流群】，点击链接加入群聊【计算机技术交流】：https://jq.qq.com/?_wv=1027&k=5V7RB2c