本文“发表于微博自媒体”，微博：@钻石草帽

本文采用知识库的方式，记录GitBook以下各方面内容：

  1. 在不同系统中安装、运行等程序层面的操作
  2. 配置、命令、插件、主题等的作用及其理解
  3. 在Gitbook.com上的应用
  4. 应用过程中遇到的问题及其解决方案

1. 安装与运行

  • 安装
    • 首先安装npm
    • 完成npm的安装后使用npm install gitbook-cli -g安装Gitbook，其中gitbook-cli是Gitbook的一个命令行工具, 通过它可以在电脑上安装和管理Gitbook的多个版本
  • 运行
    • 初始化。使用gitbook init对书籍初始化
    • 生成HTML文件。使用gitbook build生成书籍html文件，所有文件均存储于新建的_book文件夹中
    • 运行服务。使用gitbook serve运行服务器，服务器地址为http://localhost:4000/
    • 调试。使用gitbook build --debug输出错误信息
  • 更新与卸载
    • 更新。使用gitbook update更新至最新版本
    • 卸载。使用gitbook uninstall <VersionNumber>卸载对应版本的gitbook

2. 配置

2.1. 目录结构

项目或书籍的根目录下包含book.json、README.md、SUMMARY.md、GLOSSARY.md和各部分或章节文件或文件夹。

  • book.json
  • README.md
    • 对整个项目或书籍的描述，以及其他想要加入的内容
  • SUMMARY.md
    • 书籍目录
    • 首行# Summary，用于标识目录
    • 以* [标题](文件位置)的形式写明每一条目录及其引用的文件
    • 以索引层级标识目录的隶属关系
    • 每个部分可以使用标题或者----分隔符进行划分
# Summary

### Part I
* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)
<!-- 其中，”part1/“、”part2/“、”part3/“表示不同的文件夹 -->
  • GLOSSARY.md
    • 名词解释文件
    • 用于索引书中提到的名词
    • 使用二级标题标识每一个名词，每个标题下的正文为名词解释的内容 
## CDN
CDN是Content Delivery NetWork的首字母缩写，主要功能是在不同的地点缓存内容，通过负载均衡技术，将用户的请求定向到最合适的缓存服务器上去获取内容，以就近访问的方式加速用户对网站的访问，解决Internet网络拥堵状况，提高用户访问网络的响应速度

## SVG
SVG是Scalable Vector Graphics的首字母缩写，译为可缩放矢量图形，它是一种图形格式，这种图形格式允许将图形描述为图形对象的集合，例如行、矩形等，而不是颜色像素
  • 各部分或章节文件或文件夹
    • 所有的md文件都可以放在根目录下
    • 也可以用文件夹管理书籍的各个部分，如果使用文件夹管理，在SUMMARY.md文件中必须标识文件路径

2.2. book.json配置

// book.json示例
{
    "title": "TecLearning",
    "author": "Strawhat Chan",
    "description": "记录Python、算法和量化的学习记录",
    "language": "zh-hans",
    "gitbook": ">=3.2.3",
    "root": ".", // 指定根目录文件夹
    "links":{
        "sidebar": {
            "微博": "https://weibo.com/strawhatchan"
        }
    },
    "plugins": ["-katex-plus",
                "mathjax"
                ]
}
// language属性包含：en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw
// styles属性的设置
"styles":{
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}
// pluginsConfig属性的设置
"pluginsConfig": {
    "fontsettings": {
        "theme": "sepia",
        "family": "serif",
        "size": 1
    }
}

3. 插件

3.1. 插件的结构

Gitbook的插件建立在Node modules之上，package.json和index.js是插件的2个关键文件

3.1.1. package.json

  • 该文件有2个作用
    • 声明依赖、版本、所有者及其他运行插件的信息
    • 包含配置信息的细节内容，这些内容在gitbook参数中定义
  • 插件名称必须以gitbook-plugin-开头
  • engines必须包含gitbook的版本信息
  • 该文件遵循JSON-Schema指引，更多信息可阅读NPM documentation
  • package.json文件示例如下
{
    "name": "gitbook-plugin-mytest",
    "version": "0.0.1",
    "description": "This is my first GitBook plugin",
    "engines": {
        "gitbook": ">3.x.x"
    },
    "gitbook": {
        "properties": {
            "myConfigKey": {
                "type": "string",
                "default": "it's the default value",
                "description": "It defines my awesome config!"
            }
        }
    }
}

3.1.2. index.js

  • index.js是插件运行的主要入口
  • index.js文件示例如下
module.exports = {
    // Map of hooks
    hooks: {},

    // Map of new blocks
    blocks: {},

    // Map of new filters
    filters: {}
};

3.2. 发布插件

  • Gitbook插件可在NPM上发布
  • 发布插件必须在npmjs.com上创建账户
  • 通过命令npm publish发布

3.3. 私有插件

  • 私有插件可托管于Github上，通过git URLs调用
  • git URLs调用的方式为myplugin@git+https://user@hostname/owner/project.git#VisionNumber
    • myplugin表示为引入插件设定的名称
    • @git+为固定字符
    • https://user@hostname/owner/project.git为插件项目的HTTP地址
    • #VisionNumber表示版本号
  • git URLs引用文件的一般的形式为git+https://user@hostname/owner/project.git/file#commit-ish
    • file为包含路径的文件名
    • #为必要的符号
    • commit-ish为标签、sha或者分支名称

4. Gitbook.com应用

5. 问题及解决方案

6. 版本记录

7. 微博发布

  • [ ] 安装与运行
  • [ ] 配置
    • [ ] 目录结构
    • [ ] book.json配置
  • [ ] 插件
  • [ ] Gitbook.com应用
  • [ ] 问题及解决方案

results matching ""

    No results matching ""