Markdown 文檔生成工具

時間  2019-11-17
標籤 markdown 文檔 生成 工具 欄目 Markdown 简体版
原文   原文鏈接

以前用了不少Markdown 文檔生成工具，發現有幾個挺好用的，如今整理出來，方便你們快速學習。php

  • loppo: 很是簡單的靜態站點生成器
  • idoc：簡單的文檔生成工具
  • gitbook：大名鼎鼎的文檔協做工具
  • docsify：一個神奇的文檔站點生成器，簡單輕巧，無需靜態構建html

教程版：
http://me.52fhy.com/learn-markdown-generate-tool/#/css

loppo

官網： https://github.com/ruanyf/loppohtml

依賴 node.js 環境。vue

特色：
一、簡單小巧，支持自動生成目錄。
二、不支持插件。
三、原理是將 Markdown 文件編譯生成 html 文件。
四、生成的頁面很美觀、大方，支持響應式。java

安裝

全局安裝：node

$ npm install loppo -g

如何使用

建立項目：linux

$ mkdir test-loppo
$ cd test-loppo

項目目錄格式示例：android

|- test-loppo
   |- README.md
   |- docs
      |- page1.md
      |- page2.md
      |- ...

而後運行項目：git

$ loppo

會生成：github

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 環境。

特色：
一、簡單小巧，支持自動生成目錄。有幾個主題能夠選擇。
二、不支持插件。
三、原理是將 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 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 環境。

特色：
一、擴展性很是好，有社區支持。支持插件。
二、目錄須要手動配置。
三、支持生成html、pdf、epub文件。

由於 gitbook 擴展性很強，下面僅給出簡要教程，詳細教程請閱讀：https://github.com/52fhy/gitbook-use

安裝

一、安裝 gitbook 編輯器：
https://legacy.gitbook.com/editor/

二、運行下面的命令進行安裝 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 install

生成靜態網頁並運行服務器

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。

常見問題

一、gitbook生成pdf時缺乏ebook.css
找到 C:\Users\YJC\.gitbook\versions\3.2.3\lib\output\website，將copyPluginAssets.js文件中67行和112行的「confirm: true」 改成：「confirm: false」。

示例項目

一、52fhy/gitbook-use: 記錄GitBook的一些配置及插件信息
https://github.com/52fhy/gitbook-use
二、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 環境。

特色：
一、擴展性很是好，有社區支持。支持插件。
二、目錄須要手動配置。
三、發佈無需編譯生成 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.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/#/

參考資料

一、ruanyf/loppo: an extremely easy static site generator of markdown documents https://github.com/ruanyf/loppo 二、docsify https://docsify.js.org/ 三、idoc https://wangchujiang.com/idoc/index.html 四、52fhy/gitbook-use: 記錄GitBook的一些配置及插件信息 https://github.com/52fhy/gitbook-use 五、Mac環境安裝Gitbook，並導出PDF教程 - 簡書 https://www.jianshu.com/p/4824d216ad10

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程