官方文档 - 使用GitBook和Typora生成类似官方文档

本文主要介绍我使用的GitBook + Typora + Git(服务器),来编写类似的官方文档:

 

 

 

一、GitBook介绍

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown来制作精美的电子书，GitBook 并非关于 [Git]的教程。

　　GitBook是一款文档编辑工具。它的功能类似金山WPS中的Word或者微软Office中的Word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。 当然，以上的功能WPS、Office可能做得更好，但是，GitBook还有更最强大的功能：它可以用文档建立一个网站，让更多人了解你写的书，另外，最最核心的是，他支持Git，也就意味着，它是一个分布式的文档编辑工具。 你可以随时随地来编写你的文档，也可以多人共同编写文档，哪怕多人编写同一页文档，它也能记录每个人的内容，然后告诉你他们之间的区别，也能记录你的每一次改动，你可以查看每一次的书写记录和变化，哪怕你将文档都删除了，它也能找回来！ 这就是它继承Git后的厉害之处！

  1. GitBook + Markdown + Git优点：

    • 语法简单
    • 兼容性强
    • 导出方便
    • 专注内容
    • 团队协作

二、Typora介绍

Typora 是一款支持实时预览的 Markdown 文本编辑器。它有 OS X、Windows、Linux 三个平台的版本，并且由于仍在测试中，是完全免费的。

Markdown 文本编辑器，它支持且仅支持 Markdown 语法的文本编辑。在 Typora 官网 上他们将 Typora 描述为 「A truly minimal markdown editor. 」。

Typora 完全使用详解

Typora - Mac下设置图片的相对路径

相关markdown编辑器

三、安装和使用GitBook

本地安装

要求

GitBook的安装非常简单。您的系统只需满足这两个要求：

  • NodeJS
  • Windows，Linux，Unix或Mac OS X
使用NPM安装

安装GitBook的最好方法是通过 NPM 安装。在已经安装好NodeJS和NPM的电脑上，通过命令行窗口，输入以下命令安装GitBook：

npm install gitbook-cli -g

　　gitbook-cli 是安装和管理GitBook版本库的程序。它会自动安装GitBook所需的模块来创建一本书。

创建一本书

GitBook通过以下命令在当前目录创建一本书：

gitbook init

　　如果你想用现有的目录来创建一本书，你可以通过运行 gitbook init ./directory来实现

使用下面的命令预览您创建的图书：

gitbook serve

　　或者使用以下命令构建静态网站：

gitbook build
安装其他版本

gitbook命令可以方便地下载和安装不同版本的GitBook来测试你的书

gitbook fetch 4.0.0-alpha.1

使用gitbook ls-remote列出可用于安装的远程版本。

调试

您可以使用--log=debug和--debug来获得更详细的错误消息（堆栈跟踪）。例如：

gitbook build ./ --log=debug --debug
gitbook serve ./ --log=debug --debug

四、使用

1、新建mybook文件夹，初始化：gitbook init

会自动生成目录

README.md —— 书籍的介绍写在这个文件里
SUMMARY.md —— 书籍的目录结构在这里配置

2、启动Typora编辑器，引入文件夹

3、目录编辑SUMMARY.md

4、可以使用VSCode进行辅助编辑

5、浏览器浏览：gitbook serve

执行 gitbook serve 来预览这本书籍，执行命令后会对 Markdown 格式的文档进行转换，默认转换为 html 格式，最后提示 “Serving book on http://localhost:4000”

6、构建书籍：gitbook build

默认：将生成的静态网站输出到 _book 目录
指定路径：gitbook build [书籍路径] [输出路径]
指定端口：gitbook serve --port 2333
生成pdf格式：gitbook pdf ./ ./mybook.pdf
生成epub格式：gitbook epub ./ ./mybook.epub　　
生成 mobi 格式：gitbook mobi ./ ./mybook.mobi

　　注意：如果生成不了，你可能还需要安装一些工具，比如 calibre、ebook-convert，或者在 Typora 中安装 Pandoc 进行导出。

五、用 Git 做版本管理

a、在远端建好git仓库，在 mybook 目录下执行 git init 初始化仓库，执行 git remote add 添加远程仓库。接着就可以愉快地 commit，push，pull …

 
b、将生成的html放在自己的服务器上,就能直观看到你想要的文档效果

六、相关配置及优化

目录结构:
 
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|    ├── README.md
|    ├── something.md
├── chapter-2/
|    ├── README.md

　　

a、GitBook 特殊文件的功能：

文件名描述
book.json 配置数据 (optional)
README.md 电子书的前言或简介 (required)
SUMMARY.md 电子书目录 (optional)
GLOSSARY.md 词汇/注释术语列表 (optional)

b、book.json的配置说明:

变量描述
root 包含所有图书文件的根文件夹的路径，除了 book.json
structure 指定自述文件，摘要，词汇表等的路径
title 您的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
description 您的书籍的描述，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
author 作者名。在GitBook.com上，这个字段是预填的。
isbn 国际标准书号 ISBN
language 本书的语言类型 —— ISO code 。默认值是 en
direction 文本阅读顺序。可以是 rtl （从右向左）或 ltr （从左向右），默认值依赖于 language 的值。
gitbook 应该使用的GitBook版本，并接受类似于 >=3.0.0 的条件。
links 在左侧导航栏添加链接信息
plugins 要加载的插件列表(官网插件列表)
pluginsConfig 插件的配置

 

c、Gitbook 默认带有 5 个插件：

highlight - 语法高亮插件
search - 搜索插件
sharing - 分享插件
font-settings - 字体设置插件
livereload - 热加载插件

d、去除自带插件:

可以在插件名称前面加 -
 
 
"plugins": [
        "-lunr",
        "-search",导航栏查询功能（不支持中文）
        "search-pro",搜索支持中文
        "-highlight",代码高亮
        "-sharing",右上角分享功能
        "-font-settings",字体设置（最上方的"A"符号）
        "-livereload",为GitBook实时重新加载
        "expandable-chapters-small",
        "book-summary-scroll-position-saver",
        "chapter-fold",
        "multipart",
        "popup"
    ]

Tips：添加插件后要进行安装 gitbook install

e、GitBook插件列表

 

book.json文件没有的话,可以自己创建,其他文件可以自动生成

 

相关配置插件事例参考:

1、https://www.liqingbo.cn/docs/gitbook/content/config.html

2、https://zhousiwei.gitee.io/mybook/notes/gitbook_config.html

3、https://www.jianshu.com/p/427b8bb066e6

4、gitbook常用的插件

posted @ 2021-02-23 17:50  hzy_叶子  阅读(1060)  评论(0)  编辑  收藏  举报