Markdown 文档生成工具

之前用了很多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.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-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 <[email protected]>",
    "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 deploy

示例项目

这些文档是都是使用idoc生成的页面：

  1. JSLite.io - 这个是现代浏览器类似jQuery的库，体积小。
  2. idoc - 通过markdown生成静态页面的工具
  3. store.js - js本地存储操作
  4. cookie.js - js本地cookie操作
  5. iNotify - 浏览器各种方法通知
  6. Nodejs教程
  7. java代码片段

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以启用左侧菜单：

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

示例项目

  • 快速入门 - 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

时间： 2024-10-10 09:13:07

Markdown 文档生成工具的相关文章

微软开源全新的文档生成工具DocFX

微软放弃Sandcastle有些年头了,微软最近开源了全新的文档生成工具DocFX,目前支持C#和VB,类似JSDoc或Sphinx,可以从源代码中提取注释生成文档之外,而且还有语法支持你加入其他的文件链接到API添加额外的说明,DocFX会扫描你的源代码和附加的文件为你生成一个完整的HTML模版网站,你可以自己通过模版定制,目前已经内嵌了几个模版,包括静态的HTML页面和AngularJS页面.你还可以自己定制模版,具体参考 how to create custom template. 源代码

给 Web 开发人员推荐的文档生成工具——爱创课堂

工欲善其事必先利其器,在此给给 Web 开发人员推荐几款优秀的开源文档生成工具,希望能对大家有所帮助. 1.JavaScript JSDoc 3 https://www.oschina.net/p/jsdoc 这是一款根据 Javascript 文件中注释信息,生成 JavaScript 应用.库.模块的 API 文档的工具.你可以使用它记录如:命名空间.类.方法.方法参数等.该项目还衍生出了许多模板和其他工具来帮助生成和自定义文档,比如: 模板 jaguarjs-jsdoc:https://g

优于 swagger 的 java markdown 文档生成框架-01-入门使用

设计初衷 节约时间 Java 文档一直是一个大问题. 很多项目不写文档,即使写文档,对于开发人员来说也是非常痛苦的. 不写文档的缺点自不用多少,手动写文档的缺点也显而易见: 非常浪费时间,而且会出错. 无法保证及时更新.代码已经变了,但是文档还要同步修改.需要强制人来维护这一种一致性.这很难. 为什么不是 swagger-ui java 的文档有几类: jdk 自带的 doc 生成.这个以前实践给别人用过,别人用 C#,看到 java 的默认文档感觉很痛苦. 就算是我们 java 开发者,也很讨

DBImport v3.3 中文版发布：数据库数据互导及文档生成工具（IT人员必备）

前言: 好久没写文了, 距离上一篇文章是3个月前的事了,虽然工作很忙,主要还是缺少写作的内容和激情,所以没怎么动手. 之前有一个来月不断面试不同层次来应聘的人员,很有想写文的冲动,后来还是忍住了. 估计写了也是那种说人坏话.恨铁不成钢的情绪文,没啥营养,所以情绪过了就没想写了. 在公司除了管理上的事情之外,另外也研发了一套适用信息系统的快速开发框架,这个有机会再写写文和大伙分享了. 下面言归正文了. 背景: 关于这个DBImport工具,发布的版本不多,仅有:V1.0.V2.0.V3.0.V3.

使用Objective-C的文档生成工具:appledoc

前言 做项目的人多了,就需要文档了.今天开始尝试写一些项目文档.但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.象 Java 语言本身就自带 javadoc 命令,可以从源码中抽取文档.今天抽空调研了一下 objective-c 语言的类似工具. 从 stackoverflow 上找到三个比较 popular 的工具:doxygen, headdoc 和 appledoc .它们分别的官方网址如下: docxygen http://www.stack.nl/~dimitri/

文档生成工具doxygen+图像生成工具GraphViz

文档生成工具doxygen+图像生成工具GraphViz 虽然jdk自带的javadoc也很好用,不过使用doxygen+GraphViz 的组合可以生成许多强大的图(类图.协作图.文件包含/被包含图.函数调用/被调用图.类继承体系图等),另外,doxygen支持直接生成chm文档,支持LaTeX公式,如果你有一个支持php的服务器,生成的html还可以加入一个搜索框. doxygen是开源的C语言软体,可以在它的官方网站上下载到软体和源码:http://www.stack.nl/~dimitr

（转）Doxygen文档生成工具

http://blog.csdn.net/lostaway/article/details/6446786 Doxygen 是一个支持 C/C++,以及其它多种语言的跨平台文档生成工具.如同 JavaDoc, doxygen 直接从源文件中提取符合 doxygen 注释规范的注释,生成文档[1]. 1.安装 1.1 安装 Doxygen 1.7.4(Windows) 地址:ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.7.4.windows.bin

【C#附源码】数据库文档生成工具支持（Excel+Html）

[2015] 很多时候,我们在生成数据库文档时,使用某些工具,可效果总不理想,不是内容不详细,就是表现效果一般般.很多还是word.html的.看着真是别扭.本人习惯用Excel,所以闲暇时,就简单的编写了数据库文档生成工具,供大家交流学习之用,与程序员共勉.     该工具为C#控制台,以NPOI为基础,操作Excel.简单方便,简单配置.两次回车,OK!即可生成清晰的数据库文档.另外,支持生成HTML文档.源码大小7MB,OS上传不了,放到百度云盘里了:http://pan.baidu.co

使用Objective-C的文档生成工具

前言 做项目的人多了,就需要文档了.今天开始尝试写一些项目文档.但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.象Java语言本身就自带javadoc命令,可以从源码中抽取文档.今天抽空调研了一下objective-c语言的类似工具. 从stackoverflow 上找到三个比较popular的工具:doxygen, headdoc和appledoc .它们分别的官方网址如下: docxygen http://www.stack.nl/~dimitri/doxygen/ind