之前用了很多 Markdown 文档生成工具, 发现有几个挺好用的, 现在整理出来, 方便大家快速学习.
loppo: 非常简单的静态站点生成器
idoc: 简单的文档生成工具
gitbook: 大名鼎鼎的文档协作工具
docsify: 一个神奇的文档站点生成器, 简单轻巧, 无需静态构建 html
教程版:
- http://me.52fhy.com/learn-markdown-generate-tool/#/
- loppo
官网: https://github.com/ruanyf/loppo
依赖 node.JS 环境.
特点:
1, 简单小巧, 支持自动生成目录.
2, 不支持插件.
3, 原理是将 Markdown 文件编译生成 HTML 文件.
4, 生成的页面很美观, 大方, 支持响应式.
安装
全局安装:
$ NPM install loppo -g
如何使用
创建项目:
- $ mkdir test-loppo
- $ cd test-loppo
项目目录格式示例:
- |- test-loppo
- |- README.md
- |- docs
- |- page1.md
- |- page2.md
- |- ...
然后运行项目:
$ loppo
会生成:
dist/
chapters.YAML
loppo.YAML
其中 dist 是编译输出目录; chapters.YAML 是自动生成的文档目录, 根据当前目录生成, 如果增删了源文件, 需要删除该文件使得下次重新生成; loppo.YAML 是配置文件, 第一次生成后不会再变更.
loppo.YAML
该文件是配置文件:
- dir: docs
- output: dist
- site: Documents
- theme: oceandeep
- customization: false
- themeDir: loppo-theme
- direction: ltr
- id: test-loppo
我们可以手动进行修改.
dir: 源文件所在目录. 默认是当前目录下的 docs 目录.
output: 编译输出文件目录.
site: 项目文档名称. 可以自定义, 显示在页面 title 里.
theme: 主题. 默认 oceandeep. 暂时不知道有没有其他主题.
示例项目
ruanyf/survivor: 博客文集《未来世界的幸存者》
https://github.com/ruanyf/survivor
预览地址: http://survivor.ruanyifeng.com/
ruanyf/road: 博客文集《前方的路》
https://github.com/ruanyf/road
预览地址: http://road.ruanyifeng.com/
飞鸿影~ 的博客文集
http://wen.52fhy.com/
安卓学习笔记
- http://android.52fhy.com/
- 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/主题.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 deploy
示例项目
这些文档是都是使用 idoc 生成的页面:
JSLite.io - 这个是现代浏览器类似 jQuery 的库, 体积小. http://jslite.github.io/JSLite/
idoc - 通过 Markdown 生成静态页面的工具 http://jaywcjlove.github.io/idoc
store.JS - JS 本地存储操作 http://jaywcjlove.github.io/store.js
cookie.JS - JS 本地 cookie 操作 http://jslite.io/cookie.js/
iNotify - 浏览器各种方法通知 http://jaywcjlove.github.io/iNotify
Node.JS 教程 http://nodejs.jakeyu.top/
java 代码片段 http://java-snippets.javaos.cc/
gitbook
官网: https://www.gitbook.com/
依赖 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": "Go web 编程",
- "description": "build-web-application-with-golang",
- "author": "谢孟军",
- "output.name": "build-web-application-with-golang-zh",
- "pdf":{
- "fontFamily":"微软雅黑"
- }
- }
命令
列出 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".
示例项目
1,52fhy/gitbook-use: 记录 GitBook 的一些配置及插件信息
https://github.com/52fhy/gitbook-use
2,Introduction . Go Web 编程
- http://doc.52fhy.com/build-web-application-with-golang/zh/index.html
- docsify
官网: https://docsify.js.org/#/
代码块: https://github.com/docsifyjs/docsify
依赖 node.JS 环境.
特点:
1, 扩展性非常好, 有社区支持. 支持插件.
2, 目录需要手动配置.
3, 发布无需编译生成 HTML, 动态解析 md 文件.
安装
全局安装:
NPM i docsify-cli -g
如何使用
创建并初始化项目:
- $ mkdir test-docsify
- $ cd test-docsify
- # init project
- $ 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
我们可以给文档增加左侧菜单. 菜单文件名是_sidebar.md. 格式要求示例:
- <!-- docs/_sidebar.md -->
- * [Home](/) * [Guide](guide.md) * [About](about.md "关于我, 这是 title tag")
括号里可以增加 title tag, 通常用于 SEO.
保存后需要修改 index.HTML 添加 loadSidebar: true 以启用左侧菜单:
- Windows.$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 使用 https://github.com/PrismJS/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">
其它主题:
: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
示例项目
快速入门 - docsify
https://docsify.js.org/#/quickstart
介绍 - vue.js
https://cn.vuejs.org/v2/guide/
Linux C 编程一站式学习
http://me.52fhy.com/linux-c/#/
参考资料
- 1,ruanyf/loppo: an extremely easy static site generator of Markdown documents
- https://github.com/ruanyf/loppo
- 2,docsify
- https://docsify.js.org/
- 3,idoc
- https://wangchujiang.com/idoc/index.html
4,52fhy/gitbook-use: 记录 GitBook 的一些配置及插件信息
https://github.com/52fhy/gitbook-use
5,Mac 环境安装 Gitbook, 并导出 PDF 教程 - 简书
https://www.jianshu.com/p/4824d216ad10
来源: https://www.cnblogs.com/52fhy/p/10745719.html