文档工具
之前用了很多Markdown 文档生成工具，发现有几个挺好用的，现在整理出来，方便大家快速学习。
- loppo: 非常简单的静态站点生成器
- idoc：简单的文档生成工具
- gitbook：大名鼎鼎的文档协作工具
- docsify：一个神奇的文档站点生成器，简单轻巧，无需静态构建html
docsify
依赖 node.js 环境。
特点：
1、扩展性非常好，有社区支持。支持插件。
2、目录需要手动配置。
3、发布无需编译生成 html，动态解析 md 文件。
安装
全局安装：
npm i docsify-cli -g如何使用
创建并初始化项目：
$ mkdir test-docsify
$ cd test-docsify
$ docsify init ./docs执行完毕，生成 docs 目录。里面有 3 个文件：
-
.nojekyll：让 gitHub 不忽略掉以_ 打头的文件 - index.html：整个网站的核心文件
- README.md：默认页面
接下来预览一下效果：
$ docsify serve docs会在本地运行 server 服务，我们打开浏览器，输入：http://localhost:3000 即可看到 demo 页面。
项目的目录结构示例：
.
└── docs
├── README.md
├── guide.md
└── zh-cn
├── README.md
└── guide.md实际路由对应关系是：
docs/README.md => http://domain.com
docs/guide.md => http://domain.com/guide
docs/zh-cn/README.md => http://domain.com/zh-cn/
docs/zh-cn/guide.md => http://domain.com/zh-cn/guide增加一个页面
我们新增 guide.md 文件作为示例：
## docsify
官网： https://docsify.js.org/#/
代码块：https://github.com/docsifyjs/docsify
> 依赖 node.js 环境。
### 安装
全局安装：
npm i docsify-cli -g
### 如何使用
创建并初始化项目：我们启动 server 预览效果：
$ docsify serve docs浏览：http://localhost:3000/#/guide
server 启动后，我们修改文件保存后，浏览器会实时刷新。
我们可以给文档增加左侧菜单。菜单文件名是_sidebar.md。格式要求示例：
* [Home](/)
* [Guide](guide.md)
* [About](about.md "关于我，这是title tag")括号里可以增加 title tag，通常用于 SEO。
保存后需要修改 index.html 添加loadSidebar: true以启用左侧菜单：
window.$docsify = {
loadSidebar: true,
subMaxLevel: 3,
name: '',
repo: '',
auto2top: true,
search: 'auto'
}其中：
-
loadSidebar：是否显示左侧菜单 -
subMaxLevel：配置菜单层级，默认仅显示一级 -
name：配置项目名 -
repo：配置代码库地址 -
auto2top：更改路由时自动滚动到屏幕顶部 -
search：配置启用搜索功能。需要加载对应 js 文件。后面有说明。
也可以增加分组菜单，必须用 tag 键留空格，否则层级是相同的。示例：
* [首页](/)
* 开始学习
* [loppo](loppo.md "非常简单的静态站点生成器")
* [idoc](idoc.md)
* [gitbook](gitbook.md)
* [docsify](docsify.md)
* 参考配置高亮
docsify 使用 Prism 突出显示页面中的代码块。默认情况下，它仅支持 CSS，JavaScript 和 HTML。你可以使用 Prism 加载其他语言：
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-java.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-go.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-c.js"></script>
<script src="//unpkg.com/prismjs/components/prism-asm6502.js"></script>
<script src="//unpkg.com/prismjs/components/prism-makefile.js"></script>从这个库里获取更多选项支持：https://github.com/PrismJS/prism/tree/gh-pages/components。
搜索
修改 index.html ，头部引入：
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>然后配置里开启搜索：
search: 'auto'copy-code
如果需要支持代码后面显示复制按钮，可以引入该插件：
<script src="//unpkg.com/docsify-copy-code"></script>无需额外配置。
自定义导航栏
参考：https://docsify.js.org/#/custom-navbar
主题修改
仅需替换 index.html 里的vue：
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">可用的主题：
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/pure.css">其它主题： docsify-themeable ：A delightfully simple theme system for docsify.
参考：https://docsify.js.org/#/themes
配置参考
参考：https://docsify.js.org/#/configuration
插件参考
参考：https://docsify.js.org/#/plugins
发布到 GitHub Pages
参考：https://docsify.js.org/#/deploy
配置文件
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<title>Bookandmusic</title>
<link rel="icon" href="/siteinfo/favicon.ico" sizes="32x32">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
<!-- 目录样式 -->
<link rel="stylesheet" href="https://unpkg.com/docsify-plugin-toc@1.3.1/dist/light.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'bookandmusic', //文档标题，会显示在侧边栏顶部
nameLink: "/",
// coverpage: '_coverpage.md', // 封面
coverpage: false,
loadSidebar: '_sidebar.md', //侧边栏
loadNavbar: '_navbar.md', // 导航配置
notFoundPage: '_404.md', //加载自定义404页面
alias: {
'/.*/_sidebar.md': '/_sidebar.md',
'/.*/_navbar.md': '/_navbar.md', // See #301
},
autoHeader: true, //同时设置 loadSidebar 和 autoHeader 后，可以根据 _sidebar.md 的内容自动为每个页面增加标题
// subMaxLevel: 0, // 目录
auto2top: true, //切换页面后是否自动跳转到页面顶部
logo: '', //侧边栏中出现的网站图标
// themeColor: '#3F51B5', // 主题色
mergeNavbar: true, //小屏设备下合并导航栏到侧边栏
search: {
placeholder: '搜索',
noData: '找不到结果!',
depth: 6
},
pagination: {
previousText: '上一章节',
nextText: '下一章节',
crossChapter: true,
crossChapterText: true,
},
copyCode: {
buttonText: '复制到剪贴板',
errorText: '错误',
successText: '已复制'
},
progress: {
position: "top",
color: "var(--theme-color,#42b983)",
height: "3px",
},
beian: {
ICP: "京ICP备2021028097号",
NISMSP: {
number: "",
url: "",
id: ""
},
},
tabs: {
persist: true, // default
sync: true, // default
theme: 'classic', // default
tabComments: true, // default
tabHeadings: true // default
},
toc: {
tocMaxLevel: 5,
target: 'h2, h3, h4, h5, h6',
ignoreHeaders: ['<!-- {docsify-ignore} -->', '<!-- {docsify-ignore-all} -->']
},
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<!-- 折叠目录 -->
<script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
<!-- 搜索插件 -->
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
<!-- 备案插件 -->
<script src="https://cdn.jsdelivr.net/npm/docsify-beian@latest/dist/beian.min.js"></script>
<!-- 复制代码 -->
<script src="//unpkg.com/docsify-copy-code"></script>
<!-- emoji插件 -->
<script src="//unpkg.com/docsify/lib/plugins/emoji.js"></script>
<!-- 分页导航插件 -->
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
<!-- 阅读进度条插件 -->
<script src="https://cdn.jsdelivr.net/npm/docsify-progress@latest/dist/progress.min.js"></script>
<!-- alert插件 -->
<script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
<!-- tab插件 -->
<script src="https://cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
<!-- 图片缩放 -->
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
<!-- 目录插件 -->
<script src="https://unpkg.com/docsify-plugin-toc@1.3.1/dist/docsify-plugin-toc.min.js"></script>
<!-- 代码高亮 -->
<script src="//unpkg.com/prismjs/components/prism-sql.js"></script>
<script src="//unpkg.com/prismjs/components/prism-python.js"></script>
<script src="//unpkg.com/prismjs/components/prism-go.js"></script>
<script src="//unpkg.com/prismjs/components/prism-javascript.js"></script>
<script src="//unpkg.com/prismjs/components/prism-json.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
</body>
</html>gitbook
依赖 node.js 环境。
特点：
1、扩展性非常好，有社区支持。支持插件。
2、目录需要手动配置。
3、支持生成 html、pdf、epub 文件。
因为 gitbook 扩展性很强，下面仅给出简要教程，详细教程请阅读：https://github.com/52fhy/gitbook-use
安装
1、安装 gitbook 编辑器：
https://legacy.gitbook.com/editor/
2、运行下面的命令进行安装 gitbook-cli：
npm install gitbook-cli -g其中 gitbook-cli 是 gitbook 的一个命令行工具, 通过它可以在电脑上安装和管理 gitbook 的多个版本。
注意：
-
gitbook-cli 和gitbook 是两个软件 -
gitbook-cli 会将下载的gitbook 的不同版本放到~/.gitbook 中, 可以通过设置GITBOOK_DIR环境变量来指定另外的文件夹
如何使用
新建一个项目：
$ mdkir test_gitbook && cd test_gitbook初始化目录结构：
$ gitbook init├── README.md
├── SUMMARY.md使用下列命令会运行一个服务器, 通过http://localhost:4000/可以预览书籍：
gitbook serve运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件。 我们可以使用下面命令来生成网页而不开启服务器。
gitbook build目录结构
GitBook 基本的目录结构如下所示
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md-
book.json 为配置文件 -
README.md 主页 -
SUMMARY.md 目录文件
目录文件
SUMMARY.md 示例：
# Summary
## 基本使用
* [前言](introduction.md)
* [安装](installation.md)
* [命令](commands.md)
* [目录结构](structure.md)
* [配置](settings.md)
## 扩展
* [插件](plugins.md)
* [主题](themes.md)
* [bookjson](bookjson.md)配置文件
book.json 示例：
{
"title": "GitBook 简明教程",
"language": "zh-hans",
"author": "佚名",
"links": {
"sidebar": {
"书和音乐": "http://www.bookandmusic.cn"
}
},
"plugins": [
"-search",
"-lunr",
"-sharing",
"-livereload",
"github",
"donate",
"chart",
"todo",
"graph",
"puml",
"katex",
"code",
"ace",
"sitemap-general",
"mermaid-gb3",
"include-csv",
"flexible-alerts",
"chapter-fold",
"anchor-navigation-ex",
"theme-comscore"
],
"pluginsConfig": {
"anchor-navigation-ex": {
"showLevel": false,
"showGoTop": true
},
"sitemap-general": {
"prefix": "http://www.bookandmusic.cn/gitbook/comscore/"
},
"my-toolbar": {
"buttons": [
{
"label": "下载PDF",
"icon": "fa fa-file-pdf-o",
"url": "http://www.bookandmusic.cn/gitbook/comscore/book.pdf",
"position": "left",
"text": "下载PDF",
"target": "_blank"
}
]
}
},
"structure": {
"readme": "home.md"
}
}命令
列出 gitbook 所有的命令
gitbook help输出gitbook-cli的帮助信息
gitbook --help生成静态网页并运行服务器
gitbook serve生成静态网页
gitbook build生成 pdf
gitbook pdf生成 epub
gitbook epub生成时指定 gitbook 的版本, 本地没有会先下载
gitbook build --gitbook=2.0.1列出本地所有的 gitbook 版本
gitbook ls列出远程可用的 gitbook 版本
gitbook ls-remote安装对应的 gitbook 版本
gitbook fetch 标签/版本号更新到 gitbook 的最新版本
gitbook update卸载对应的 gitbook 版本
gitbook uninstall 2.0.1指定 log 的级别
gitbook build --log=debug输出错误信息
gitbook builid --debug注：生成 pdf、epub 需要安装 calibre 插件，下载链接：https://calibre-ebook.com/download 。Mac 环境需要一个命令 sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin。
常见问题
1、gitbook 生成 pdf 时缺少 ebook.css
找到 C:\Users\YJC\.gitbook\versions\3.2.3\lib\output\website，将copyPluginAssets.js文件中 67 行和 112 行的 “confirm: true” 改为：“confirm: false”。
2、解决静态网页不能跳转问题
在导出的文件夹目录下找到gitbook->theme.js文件
找到下面的代码搜索
if(m)for(n.handler&&将if(m)改成if(false)
if(false)for(n.handler&&(i=n,n=i.handler,o=i.selector),o&&de.find.matchesSelector(Ye,o),n.guid||(n.guid=de.guid++),(u=m.events)||(u=m.events={}),(a=m.handle)||(a=m.handle=function(t){return"undefined"!=typeof de&&de.event.triggered!==t.type?de.event.dispatch.apply(e,arguments):void 0}),t=(t||"").match(qe)||[""],l=t.length;l--;)s=Ze.exec(t[l])||[],h=g=s[1],d=(s[2]||"").split(".").sort(),h&&(f=de.event.special[h]||{},h=(o?f.delegateType:f.bindType)||h,f=de.event.special[h]||{},c=de.extend({type:h,origType:g,data:r,handler:n,guid:n.guid,selector:o,needsContext:o&&de.expr.match.needsContext.test(o),namespace:d.join(".")},i),(p=u[h])||(p=u[h]=[],p.delegateCount=0,f.setup&&f.setup.call(e,r,d,a)!==!1||e.addEventListener&&e.addEventListener(h,a)),f.add&&(f.add.call(e,c),c.handler.guid||(c.handler.guid=n.guid)),o?p.splice(p.delegateCount++,0,c):p.push(c),de.event.global[h]=!0)
idoc
官网： https://github.com/jaywcjlove/idoc
依赖 node.js 环境。
特点：
1、简单小巧，支持自动生成目录。有几个主题可以选择。
2、不支持插件。
3、原理是将 Markdown 文件编译生成 html 文件。
安装
全局安装：
$ sudo npm install idoc -g如何使用
创建并初始化项目：
$ mkdir test-idoc
$ cd test-idoc
# 初始化
$ idoc init填入必要的项目信息，初始化完成。会在项目目录下生成：
md/
|-- index.md
package.json运行 idoc server 预览生成的静态页面。默认预览地址为 http://localhost:1987/
预览的时候改动md文件，浏览器刷新可以看到改动后的内容。
其中 初始化 步骤也可以手动执行，把目录和配置文件建好就行了。
目录结构
idoc对目录结构没有要求，只要你把md文件放在md/目录下面，idoc会自动识别。支持子目录。例如：
md/
|-- 首页.md
|-- 关于.md
|-- 使用方法/
|-- 命令文档.md
|-- 命令文档2.md如果有子目录，生成的文档导航栏也会有子菜单。
配置文件
package.json文件。
{
"name": "idoc",
"version": "0.0.1",
"description": "",
"keywords": [
""
],
"homepage": "http://JSLite.io",
"author": "jaywcjlove <wowohoo@qq.com>",
"repository": {
"type": "git",
"url": "https://github.com/jaywcjlove/idoc"
},
"licenses": "MIT",
"idoc": {
"theme": "default",
"logo": "idoc-logo.svg",
"md": [
"首页.md",
{
"使用方法": [
"主题文件.md",
"初始化.md",
"配置说明.md"
]
},
"关于.md"
]
}
}其中 idoc.md块无需手动配置，idoc build 自动生成。其它配置无需多说明，也能看的懂。
主题
支持：
- handbook
- default
- resume
参考：https://wangchujiang.com/idoc/html/%E4%B8%BB%E9%A2%98.html
常用命令
- build
生成静态 HTML 页面到指定目录中。
$ idoc build- watch
监控 md 文件发生变化自动 build。
$ idoc watch- server
打开本地静态 html 服务器，预览你生成的页面。
$ idoc server- clean
清除生成的静态文件。
$ idoc clean- theme
$ idoc theme 与 $ idoc -t 相同
选择默认主题或者第三方主题，默认两个主题 handbook 或者 default。
# 选择主题
# 第三方主题，克隆到当前跟目录就可以使用命令选择了
$ idoc theme
# theme 简写 －t
$ idoc -t
# 制作主题 需要指定制作的主题目录
$ idoc -t ~/git/idoc-theme-slate/- deploy
将文档部署到 git 仓库的 gh-pages 分支中。
目前需要手动添加分支。
$ idoc deployloop
官网： https://github.com/ruanyf/loppo
依赖 node.js 环境。
特点： 1、简单小巧，支持自动生成目录。
2、不支持插件。
3、原理是将 Markdown 文件编译生成 html 文件。
4、生成的页面很美观、大方，支持响应式。
安装
全局安装：
$ npm install loppo -gCopy to clipboardErrorCopied如何使用
创建项目：
$ mkdir test-loppo
$ cd test-loppo项目目录格式示例：
|- test-loppo
|- README.md
|- docs
|- page1.md
|- page2.md
|- ...然后运行项目：
$ loppo会生成：
dist/
chapters.yml
loppo.yml其中 dist是编译输出目录；chapters.yml是自动生成的文档目录，根据当前目录生成，如果增删了源文件，需要删除该文件使得下次重新生成；loppo.yml是配置文件，第一次生成后不会再变更。
loppo.yml
该文件是配置文件：
dir: docs
output: dist
site: Documents
theme: oceandeep
customization: false
themeDir: loppo-theme
direction: ltr
id: test-loppoCopy to clipboardErrorCopied我们可以手动进行修改。
- dir： 源文件所在目录。默认是当前目录下的
docs目录。 - output：编译输出文件目录。
- site：项目文档名称。可以自定义，显示在页面 title 里。
- theme：主题。默认oceandeep。暂时不知道有没有其他主题。
Hexo
Hexo是一款基于Node.js的静态博客框架，依赖少易于安装使用，可以方便的生成静态网页托管在GitHub和Coding上，是搭建博客的首选框架。大家可以进入hexo官网进行详细查看，因为Hexo的创建者是台湾人，对中文的支持很友好，可以选择中文进行查看。
注意: 查看文档以获取更多信息。如果使用Hexo时遇到任何问题，可以在故障排除中找到答案，或者可以在GitHub上询问。
安装
- git和nodejs安装好后，就可以安装hexo了
npm install hexo-cli -g
npm install hexo --save依旧用hexo -v查看一下版本
至此就全部安装完了。
使用
初始化一下hexo
hexo init创建一个新帖子
$ hexo new "我的新帖子"更多信息：写作
运行服务器
$ hexo server更多信息：服务器
生成静态文件
$ hexo generate更多信息：生成
部署到远程站点
$ hexo deploy更多信息：部署
常见问题
Hexo中添加本地图片
把主页配置文件
_config.yml 里的post_asset_folder:这个选项设置为true在你的hexo目录下执行这样一句话
npm install hexo-asset-image --save，这是下载安装一个可以上传本地图片的插件等待一小段时间后，再运行
hexo n "xxxx"来生成md博文时，/source/_posts文件夹内除了xxxx.md文件还有一个同名的文件夹最后在
xxxx.md中想引入图片时，先把图片复制到xxxx这个文件夹中，然后只需要在xxxx.md中按照markdown的格式引入图片：
xxxx是这个md文件的名字，也是同名文件夹的名字。只需要有文件夹名字即可，不需要有什么绝对路径。你想引入的图片就只需要放入xxxx这个文件夹内就好了，很像引用相对路径。