Gitbook的实用技巧专栏

·  阅读 13753

MedusaSorcerer的博客


专栏目录

专栏详情

Gitbook

Gitbook介绍

GitBook 是一个基于 Node.js 的命令行工具
可用 Github/GitMarkdown 组合制作成精美的电子文档
GitBook支持输出多种文档格式:
    * 静态站点: GitBook默认输出格式, 生成的静态站点
    * PDF: 需要安装 gitbook-pdf
    * eBook: 需要安装ebook-convert
    * 单HTML网页: 支持将内容输出为单页HTML, 不过一般用在将电子书格式转换为PDFeBook的中间过程
    * JSON: 一般用于电子书的调试或元数据提取
使用GitBook制作电子书, 必备两个文件: README.md[主页面] SUMMARY.md[侧边栏页面]
复制代码

Gitbook安装

# 安装Gitbook需要node.js作为前提依赖, 安装时确保主机已经存在node.js
node -v

# 安装Gitbook多版本托管工具, 可同时托管多个Gitbook版本, 且下载最新版的Gitbook驱动
npm install gitbook-cli -g

# 验证下载是否成功
gitbook -V

# 下载历史版本[下载3.0.0版本]
# 3.2.3版本确保为不可用版本, 推荐使用3.0.0
gitbook fetch 3.0.0

# 进入到你的项目文件夹, 初始化一个Gitbook项目
gitbook init

# 生成README.md 和 SUMMARY.md 两个基本文件

# 启动服务
gitbook serve

# 指定gitbook版本启动
gitbook serve --gitbook=3.0.0

# 获取帮助
gitbook --help

# 卸载指定版本Gitbook[卸载3.2.3版本]
gitbook uninstall 3.2.3

# 生成静态网页
gitbook build

# 指定gitbook版本生成静态文件,如果本地没有将先下载
gitbook build --gitbook=3.0.0

# 列出本地所有的gitbook版本
gitbook ls

# 列出远程可用的gitbook版本
gitbook ls-remote

# 更新到gitbook的最新版本
gitbook update

# 安装配置依赖插件
gitbook install

# 指定log的级别
gitbook build --log=debug

# 输出错误信息
gitbook builid --debug

# 将 Gitbook 输出为 PDF 文件
gitbook pdf . [PDF_Name]
复制代码

Gitbook简单使用

README.md 中撰写Gitbook项目的主界面, 而 SUMMARY.md 是Gitbook界面中侧边栏的属性
README.md示例

# 主界面简介
------
此文档的简单描述

### 目录介绍
* [目录1](1.md)
* [目录2](2.md)
* [目录3](2.md)
* [目录4](4.md)
复制代码

SUMMARY.md示例

* [目录1](1.md)
* [目录2](2.md)
* [目录3](2.md)
* [目录4](4.md)
复制代码

项目根目录下可以创建 book.json 实现全局配置文件信息

{
    "title": "MedusaSorcerer的博客文档",
    "author": "MedusaSorcerer",
    "description": "MedusaSorcerer的博客文档",
    "language": "zh-hans",
    "gitbook": "3.0.0",
    "structure": {
        "readme": "README.md"
    },
    "plugins": [
        "-highlight",
        "-github",
        "-search",
        "-lunr",
        "livereload",
        "back-to-top-button",
        "code",
        "prism",
        "copy-code-button",
        "search-pro",
        "splitter",
        "-sharing-plus",
        "tbfed-pagefooter",
        "click-reveal"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "modify_label": "该文件修订时间:",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    },
    "links": {
        "sidebar": {
            "博客主页": "https://juejin.cn/user/2805609406139950"
        },
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "weibo": false,
            "all": false
        }
    }
}
复制代码
关键字描述示例
title项目标题MedusaSorcerer的博客文档
author项目作者MedusaSorcerer
description项目描述信息-
language项目语言查看下表
gitbookGitbook版本信息3.0.0
structure结构信息{"readme": "README.md"} 指定readme的文件
plugins需要安装或者禁用的插件名称-
pluginsConfig安装的插件需要自定义的配置-
links.sidebar文档添加其他链接地址{"博客主页": "juejin.cn/user/280560… {名称:地址}
links.sharing对文档的图标链接是否启用的配置-

支持的语言列表, 版本之间存在差异, 仅供参考

语言简写描述语言简写描述
en英语ar阿拉伯语
bn马来语cs捷克语
de德语es西班牙语
fa波斯语fi芬兰语
fr法语he希伯来语
it意大利语ja日语
ko韩语no挪威语
pl波兰语pt葡萄牙语
ro罗马尼亚语ru俄语
sv瑞典语uk乌克兰语
vi越南语--
zh-hans简体汉语zh-tw繁体汉语

Gitbook插件介绍

安装的插件使用 "插件名" 注册在 plugins 里面即可, 禁用的插件使用 "-插件名"注册在 plugins 里面即可
默认启用的插件 highlight search sharing font-settings livereload

插件名称描述举个栗子
highlight代码高亮-
search导航栏英文检索功能-
font-settings字体设置-
livereload为GitBook实时重新加载-
disqus添加disqus评论"plugins": [
    "disqus"
],
"pluginsConfig": {
    "disqus": {
        "shortName": "gitbookuse"
    }
}
search-pro支持中文搜索, 需要将
默认的search插件去掉
"plugins": [
    "-search",
    "search-pro"
],
"pluginsConfig": {
    "search-pro": {
        "cutWordLib": "nodejieba",
        "defineWord" : ["Gitbook Use"]
    }
}
advanced-emoji支持emoji表情"plugins": [
    "advanced-emoji"
]
github添加github图标"plugins": [ 
    "github" 
],
"pluginsConfig": {
    "github": {
        "url": "juejin.cn/user/280560…
    }
}
ace使gitbook支持ace"plugins": [
    "ace"
]
emphasize为文字加上底色"plugins": [
    "emphasize"
]
katex支持数学公式"plugins": [
    "katex"
]
include-codeblock使用代码块的格式显
示所包含文件的内容
"plugins": [
    "include-codeblock"
]
mermaid支持渲染Mermaid图表"plugins": [
    "mermaid"
]
splitter使侧边栏宽度可自由调节"plugins": [
    "splitter"
]
sharing分享当前页面, 默认插件"plugins": [
    "-sharing"
]
"pluginsConfig": {
    "sharing": {
        "weibo": true,
        "facebook": true,
        "twitter": true,
        "google": false,
        "instapaper": false,
        "vk": false,
        "all": [
            "facebook", "google", "twitter",
                "weibo", "instapaper"
        ]
    }
}
tbfed-pagefooter为页面添加页脚"plugins": [
   "tbfed-pagefooter"
],
"pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"Copyright &copy zhangjikai.com 2015",
        "modify_label": "该文件修订时间:",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
    }
}
toggle-chapters使左侧的章节目录可以折叠"plugins": [
    "toggle-chapters"
]
sectionx将页面分块显示"plugins": [
    "sectionx"
]
codeblock-filename为代码块添加文件名称"plugins": [
    "codeblock-filename"
]
gagoogle 统计"plugins": [
    "ga"
 ],
"pluginsConfig": {
    "ga": {
        "token": "UA-XXXX-Y"
    }
}
baidu百度统计"plugin": [
    "baidu"
 ],
"pluginsConfig": {
    "baidu": {
        "token": "YOUR TOKEN"
    }
}

Gitbook错误处理

  1. 执行 npm install gitbook-cli -g 的时候下载失败
    进入你的 Users\当前用户\AppData\Roaming\npm\node_modules 目录下
    查看是否有 gitbook-cli 目录
    
    如果目录存在, 删除 gitbook-cli 目录
    如果目录不存在, 使用 npm 卸载 Gitbook 遗留文件
    再重新执行下载即可成功
    复制代码
  2. 修改项目文件保存后, gitbook serve 不支持热加载
    当你修改 Gitbook 项目保存后, serve 重启的时提示无法使用 mkdir 操作, 以至于不能达到重启的目的
    那么你需要进行以下操作:
    • 找到你下载的gitbook版本文件夹: 一般位于Users\当前用户\.gitbook\versions\下会有对应版本号的文件夹名称
    • 在对应版本文件夹内找到lib\cli\serve.js文件
    • 复制以下代码放置serve.js文件中
      /* 代码首行 */
      const fs=require("fs");
      
      /* 任意空白位置 */
      function deleteFolder(path) {
      let files = [];
      if( fs.existsSync(path) ) {
          files = fs.readdirSync(path);
          files.forEach(function(file,index){
              let curPath = path + "/" + file;
              if(fs.statSync(curPath).isDirectory()) {
                  deleteFolder(curPath);
              } else {
                  fs.unlinkSync(curPath);
              }
          });
          fs.rmdirSync(path);
          }
      }
      复制代码
    • serve.js找到函数体generateBook
    • 在函数内var outputFolder = getOutputFolder(args);后另起一行写入以下代码
      if (server.isRunning()) deleteFolder(outputFolder)
      复制代码
    • 保存退出, 重启gitbook, 发现热加载生效了
    注意: 当你停止服务的时候, 若服务没有自动删除 _book 文件夹时, 你需要手动删除 _book 文件夹 ``
  3. 安装 Gitbook 后没有找到 gitbook 指令
    需要在你的环境变脸中添加 Gitbook 的变量 Path
    Users\当前用户\AppData\Roaming\npm
    复制代码
  4. 使用 gitbook pdf . pdfname.pdf 执行生成 PEF 文件编码错误
    ① 在 https://calibre-ebook.com/ 下载安装包安装在本地
    
    ② 安装完成后右键安装桌面图标找到安装路径并复制
    
    ③ 右键我的电脑 -> 属性 -> 高级系统设置 -> 环境变量 -> 用户变量 -> 选中PATH -> 编辑
    
    ④ 将刚刚复制的文件路径粘贴在末尾空白行保存退出
    
    ⑤ 重新打开 CMD 或者其他交互窗口, 执行 gitbook 命令
    复制代码
分类:
代码人生
标签:
收藏成功!
已添加到「」, 点击更改