Gitbook 博客 使用总结
目录
目录
Gitbook 博客 使用总结
Gitbook 现在是越来越垃圾了，一堆非常明显的 bug 一年多了也没有修复，绝对不建议再继续使用了！
GitBook helps you publish beautiful docs for your users and centralize 集中 your teams' knowledge for advanced collaboration 高级协作.
Gitbook 是基于Node.js的命令行工具，用来创建漂亮的电子书，它使用Markdown或AsciiDoc语法来撰写内容，用Git进行版本控制，且可以托管在Github上。Gitbook 可以将作品编译成网站、PDF、ePub 和 MOBI 等多重格式。
环境准备
- 安装
Node.js：node -v - 安装
GitBook：npm i -g gitbook-cli - 检验是否安装成功：
gitbook -V - 安装 GitBook Editor，实际上并没有什么卵用
可能会一直报错
...\node_global\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 ...\node_global\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js:287:18
at FSReqCallback.oncomplete (node:fs:199:5)
原因是 nodejs 的版本不对，不支持这个 gitbook，解决方法 参考这里：打开 [polyfills.js](file:///D:/_dev/node.js/node_global/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js)，注释掉 statFix 的 3 个调用的地方(在62、63、64这三行)。
上面的解决方案现在已经不行了！stackoverflow 上的这个方案也不行了！
基本使用
- 进入一个你要写书的目录，执行命令
gitbook init
如果目录中存在
SUMMARY.md文件，则会根此文件的目录结构初始化各个章节文件，否则他会会自动创建SUMMARY.md文件。项目中一般还会包含一个README.md说明文档。
- 执行命令
gitbook serve运行服务，在编辑内容后可实时预览
首次运行该命令后，会在项目文件夹中生成一个
_book文件夹，里面的内容即为生成的 html 文件，然后在浏览器地址栏中输入 http://localhost:4000 便可预览书籍。
- 可以使用命令
gitbook build来生成网页而不开启服务器
项目目录结构
GitBook 项目基本的目录结构如下所示：
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
| ├── README.md
| └── something.md
└── chapter-2/
├── README.md
└── something.md
章节文件：SUMMARY.md
这个文件主要决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系。我们可以通过使用标题或者水平分割线将 GitBook 分为几个不同的部分，下面是一个简单的示例：
# 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)
配置文件：book.json
该文件主要用来存放配置信息，常用配置如下：
- title：本书标题
- author：本书作者
- description：本书描述
- language：本书语言，中文设置 "zh-hans" 即可
- gitbook：指定使用的 GitBook 版本
- styles：自定义页面样式
- structure：指定 Readme、Summary、Glossary 和 Languages 对应的文件名
- links：在左侧导航栏添加链接信息，例如个人站点
- plugins：配置使用的插件，例如分享、GitHub
- pluginsConfig：配置插件的属性，比如GitHub的仓库地址
{
"title": "包青天的GitBook",
"author": "包青天",
"description": "欢迎访问包青天的GitBook",
"language": "zh-hans",
"gitbook": "3.2.3",
"styles": {
"website": "./styles/website.css"
},
"structure": {
"readme": "README.md"
},
"links": {
"sidebar": {
"我的博客": "http://www.cnblogs.com/baiqiantao",
"我的GitHub": "https://github.com/baiqiantao"
}
},
"plugins": [
"-sharing",
"anchors",
"github"
],
"pluginsConfig": {
"github": {
"url": "https://github.com/baiqiantao"
}
}
}
常用命令
常用命令
gitbook init # 初始化目录文件
gitbook build [书籍路径] [输出路径] # 构建书籍，生成静态网页，默认输出到 _book 目录
gitbook serve [--port 端口号] # 包含build命令，生成静态网页并运行服务器
gitbook pdf ././mybook.pdf # 生成 pdf/epub/mobi 格式的电子书
gitbook help # 列出gitbook所有的命令
gitbook --help # 输出gitbook-cli的帮助信息
gitbook ls # 列出本地所有的gitbook版本
gitbook ls-remote # 列出远程可用的gitbook版本
gitbook fetch 标签/版本号 # 安装对应的gitbook版本
gitbook update # 更新到gitbook的最新版本
gitbook uninstall 2.0.1 # 卸载对应的gitbook版本
gitbook --help
Usage: gitbook [options] [command]
Options:
-v, --gitbook [version] specify GitBook version to use
-d, --debug enable verbose error
-V, --version Display running versions of gitbook and gitbook-cli
-h, --help output usage information
Commands:
ls List versions installed locally
current Display currently activated version
ls-remote List remote versions available for install
fetch [version] Download and install a <version>
alias [folder] [version] Set an alias named <version> pointing to <folder>
uninstall [version] Uninstall a version
update [tag] Update to the latest version of GitBook
help List commands for GitBook
* run a command with a specific gitbook version
gitbook help
build [book] [output] build a book
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
--[no-]timing Print timing debug information (Default is false)
serve [book] [output] serve the book as a website for testing
--port Port for server to listen on (Default is 4000)
--lrport Port for livereload server to listen on (Default is 35729)
--[no-]watch Enable file watcher and live reloading (Default is true)
--[no-]live Enable live reloading (Default is true)
--[no-]open Enable opening book in browser (Default is false)
--browser Specify browser for opening book (Default is )
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
install [book] --log install all plugins dependencies
parse [book] --log parse and print debug information about a book
init [book] --log setup and create files for chapters
pdf [book] [output] --log build a book into an ebook file
epub [book] [output] --log build a book into an ebook file
mobi [book] [output] --log build a book into an ebook file
插件
Gitbook 支持使用插件来进行个性化定制。
GitBook 默认带有 5 个插件，如果要去除自带的插件，可以在插件名称前面加-。
Gitbook目前一共有700个左右的插件，如果要使用其他插件，可以在plugins中添加插件名称，然后在pluginsConfig中配置插件。
如果在执行 build 或 server 命令时提示要使用的插件不存在，只需在终端输入 gitbook install ./ 即可自动安装缺少的插件。如果要指定插件的版本，可以使用plugin@0.3.1。
一些插件
默认插件
- sharing：默认的分享插件。
- fontsettings：默认的字体、字号、颜色设置插件。
- search：默认搜索插件。
- highlight：默认的代码高亮插件，通常会使用 prism 来替换。
必备插件
- anchor-navigation-ex：导航扩展，增加锚点，返回顶部，显示序号
- anchor-navigation：锚点导航(为什么不能用？)
- donate：捐赠打赏按钮插件
- splitter：在左侧目录和右侧内容之间添加一个可以拖拽的栏，用来调整两边的宽度。
- tbfed-pagefooter：自定义页脚，显示版权和最后修订时间。
- ad：在每个页面顶部和底部添加广告或任何自定义内容。
常用插件
- editlink：内容顶部显示
编辑本页链接。 - book-summary-scroll-position-saver：自动保存左侧目录区域导航条的位置。
- prism：基于 Prism 的代码高亮。
- atoc：插入 TOC 目录。
- ace：插入代码高亮编辑器。
- include-codeblock：通过引用文件插入代码。
- expandable-chapters：收起或展开章节目录中的父节点。
- anchors：标题带有 github 样式的锚点。
- github：在右上角显示 github 仓库的图标链接。
- github-buttons：显示 github 仓库的 star 和 fork 按钮。
可能有用的插件
- redirect：页面跳转(重定向)。
- sectionx：分离各个段落，并提供一个展开收起的按钮。
- favicon：为网站添加了favicon和Apple Touch图标。
- image-captions：抓取内容中图片的
alt或title属性，在图片下面显示标题。 - mermaid：使用流程图。
- latex-codecogs：使用数学方程式。
- disqus：添加 disqus 评论插件。
- sitemap：生成站点地图。
- baidu：使用百度统计。
- ga：添加 Google 统计代码。
- duoshuo：使用多说评论。
一般用不到的插件
- chart：使用 C3.js 图表。
- youtubex：插入 YouTube 视频。
- fbqx：使用填空题。
- mcqx：使用选择题。
- spoiler：隐藏答案，当鼠标划过时才显示。
- styles-sass：使用 SASS 替换 CSS。
- styles-less：使用 LESS 替换 CSS。
输出 PDF
下载插件 calibre-ebook，安装后，程序会自动将包含ebook-convert.exe的文件夹添加到 PATH 变量中(如果没有，请手动添加)。
npm install svgexport -g
npm install ebook-convert -g
gitbook pdf/epub/mobi //生成电子书
个性化配置：
pageNumbers：是否添加页码，默认是truefontSize：字体大小，默认是12fontFamily：字体，默认字体是ArialpaperSize：default is a4, options are 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter'margin.top/bottom/right/left：Top margin (default is 56/62)
{
"pdf": {
"fontFamily": "Arial",
"fontSize": 12,
"margin": {
"bottom": 56,
"left": 62,
"right": 62,
"top": 56
},
"pageNumbers": true,
"paperSize": "a4"
},
"pluginsConfig": {
"fontSettings": {
"family": "msyh",
"size": 2,
"theme": "white"
},
"plugins": [
"yahei",
"katex",
"-search"
]
}
}
2019-3-12
本文来自博客园，作者：白乾涛，转载请注明原文链接：https://www.cnblogs.com/baiqiantao/p/10518914.html
