一、介绍
什么是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