Mac安装和使用GitBook

简介: Mac安装和使用GitBook

1 安装gitbook

npm i gitbook-cli -g

2 初始化gitbook项目

新建一个项目目录,终端执行以下命令

gitbook init

初始化过程遇到以下问题。

问题1:


xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance


检查了一下,本地没有安装Xcode,可以在appstore中,搜索xcode安装。


问题2:

TypeError: cb.apply is not a function

详细错误如下:

/data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
 
TypeError: cb.apply is not a function
    at /data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:169:5)

打开polyfills.js文件,找到这个函数

function statFix (orig) {
  if (!orig) return orig
  // Older versions of Node erroneously returned signed integers for
  // uid + gid.
  return function (target, cb) {
    return orig.call(fs, target, function (er, stats) {
      if (!stats) return cb.apply(this, arguments)
      if (stats.uid < 0) stats.uid += 0x100000000
      if (stats.gid < 0) stats.gid += 0x100000000
      if (cb) cb.apply(this, arguments)
    })
  }
}

在第62-64行调用了这个函数

// fs.stat = statFix(fs.stat)
// fs.fstat = statFix(fs.fstat)
// fs.lstat = statFix(fs.lstat)

把这三行代码注释掉就解决报错了。

注释掉之后,重新执行初始化,成功创建项目。

初始化完成后,在执行目录中生成README.md 和 SUMMARY.md 两个文件。


3 打包GitBook项目

gitbook build

本地构建不运行服务。

打包完成后,打包文件默认输出到 _book/目录,在项目根目录中。


4 运行GitBook服务

gitbook serve

本地构建运行服务。

执行后,可通过浏览器访问 http://localhost:4000 实时预览。

5 GitBook常用命令

  • 安装 GitBook:npm i gitbook-cli -g
  • 初始化 GitBook 项目:gitbook init
  • 安装 GitBook 依赖:gitbook install
  • 开启 GitBook 服务:gitbook serve
  • 打包 GitBook 项目:gitbook build
  • GitBook 命令行查看:gitbook -help
  • GitBook 版本查看:gitbook -V

6 GitBook目录结构

- GitBook
    _book
    - README.md
    - SUMMARY.md
    - book.json
    - GLOSSARY.md
    - LANGS.md

README.md 是默认首页文件,相当于网站的首页 index.html ,一般是介绍文字或相关导航链接.


SUMMARY.md 是默认概括文件,主要是根据该文件内容生成相应的目录结构,同 README.md 一样都是被 gitbook init 初始化默认创建的重要文件.


_book 是默认的输出目录,存放着原始 markdown 渲染完毕后的 html 文件,可以直接打包到服务器充当静态网站使用。一般是执行 gitbook build 或 gitbook serve 自动生成的.


book.json 是配置文件,用于个性化调整 gitbook 的相关配置,如定义电子书的标题、封面、作者等信息。虽然是手动创建但一般是必选的.


GLOSSARY.md 是默认的词汇表,主要说明专业词汇的详细解释,这样阅读到专业词汇时就会有相应提示信息,也是手动创建但是可选的.


LANGS.md 是默认的语言文件,用于国际化版本翻译和 GLOSSARY.md 一样是手动创建但是可选的.

7 book.json配置文件说明

title:网站标题

author:网站作者

description:网站功能描述

language:网站使用语言

styles:网站额外配置的样式表

plugins:网站使用的插件

pluginsConfig:网站使用的插件的额外配


示例:

{
"title": "这里是标题",
"author": "这里是作者",
"description": "这里是描述",
"language": "zh-hans",
"plugins": [
            "-highlight",
            "copy-code-button",
            "search-pro",
            "-search",
            "-lunr",
            "expandable-chapters",
            "splitter",
            "-sharing",
            "github-buttons",
            "donate",
            "tbfed-pagefooter",
            "baidu-tongji",
            "anchor-navigation-ex"
          ],
"pluginsConfig": {
        "github-buttons": {
                "buttons": [
                        {
                            "user": "username",
                            "repo": "blog",
                            "type": "star",
                            "count": true,
                            "size": "small"
                        },
                        {
                            "user": "username",
                            "width": "160",
                            "type": "follow",
                            "count": true,
                            "size": "small"
                        }
                   ]
              },
        "donate": {
                "button": "打赏",
                "wechatText": "微信打赏",
                "wechat": "***.jpg"
                },
        "tbfed-pagefooter": {
                "copyright":"Copyright Description",
                "modify_label": "该文件修订时间:",
                "modify_format": "YYYY-MM-DD HH:mm:ss"
                },
        "baidu-tongji": {
                "token": "XXXXX"
                },
        "anchor-navigation-ex": {
                "showLevel": false
                }
        }
}

待续:

GitBook支持构建多语言文档,实现站点国际化

GitBook安装评论插件,实现可留言的文档系统

相关文章
|
1月前
|
开发工具 git iOS开发
Mac 安装软件包管理工具Homebrew
Mac 安装软件包管理工具Homebrew
|
3月前
|
Unix 网络安全 iOS开发
Mac 电脑如何安装Wireshark?
Mac 电脑如何安装Wireshark?
Mac 电脑如何安装Wireshark?
|
4月前
|
编解码 Linux Android开发
安卓投屏神器 Scrcpy 安装与使用(支持 Mac、Windows、Linux)
安卓投屏神器 Scrcpy 安装与使用(支持 Mac、Windows、Linux)
235 0
|
9天前
|
Java Android开发 芯片
Mac M芯片安装DBeaver Ultimate
Mac M芯片安装DBeaver Ultimate
14 0
Mac M芯片安装DBeaver Ultimate
|
4月前
|
Kubernetes API Docker
Mac docker-desktop 安装单机版k8s
Mac docker-desktop 安装单机版k8s
105 0
|
1月前
QT 5.14.2版本 MAC环境安装部署流程
QT 5.14.2版本 MAC环境安装部署流程
|
1月前
|
iOS开发 MacOS Python
Mac安装pip报错的解决办法
Mac安装pip报错的解决办法
|
1月前
|
存储 Ubuntu Linux
如何在 Mac M1 (Apple Silicon) 上安装 ABAP 1909
如何在 Mac M1 (Apple Silicon) 上安装 ABAP 1909
14 0
|
2月前
|
NoSQL 关系型数据库 MySQL
Windows、Linux、Mac安装数据库(mysql、MongoDB、Redis)#0
不同系统下进行MySQL安装、MongoDB安装、Redis安装【2月更文挑战第5天】
441 5
Windows、Linux、Mac安装数据库(mysql、MongoDB、Redis)#0
|
2月前
|
关系型数据库 MySQL 数据安全/隐私保护
【MySQL】 Docker 安装 MySQL8.0(mac)
【MySQL】 Docker 安装 MySQL8.0(mac)