开发工具总结(12)之GitBook制作文档并发布到GitHub
本文出自 AWeiLoveAndroid的博客
熟悉git的朋友们,如果使用GitBook,一定会是最佳搭档。因为gitbook是最简洁的,你只要写好你的MD文档,然后用gitbook命令生成html相关文件,传到github即可浏览。或者你直接登陆gitbook,使用网页端编辑,然后也可以直接预览效果。下面讲解一下Gitbook如何制作文档。
一、GitBook制作文档并发布到GitHub
1、npm全局安装GitBook 命令行工具
命令行: npm install gitbook-cli -g
如图所示:
npm安装gitbook命令行
下载后的相关路径为:
C:UsersAdministratorAppDataRoamingnpm-cachegitbook
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-asciidoc
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-html
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-markdown
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-fontsettings
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-highlight
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-livereload
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-lunr
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-search
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-sharing
C:UsersAdministratorAppDataRoamingnpm-cachegitbook-plugin-theme-default
在npm-cacheregistry.npm.taobao.org
路径也有:
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-asciidoc
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-html
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-markdown
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-fontsettings
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-highlight
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orgitbook-plugin-livereload
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-lunr
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-search
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-sharing
C:UsersAdministratorAppDataRoamingnpm-cacheregistry.npm.taobao.orggitbook-plugin-theme-default
临时缓存路径(其中xxx换成电脑里面具体的数字字母组合即可):
C:UsersAdministratorAppDataLocalTemptmp-xxxode_modulesgitbooknode_modules
2、创建文件和初始化
1.新建一个文件夹
mkdir gitbook-note
2.进入到文件夹
cd gitbook-note
3.进行初始化
gitbook init
初次初始化会安装GitBook, 这里下载的是GitBook-3.2.3,如果不访问外国网站非常慢。
初始化
访问外国网站之后,就很快了。如图:
git init命令行(必须访问外国网站)
gitbook init会自动生成两个文件README.md
和SUMMARY.md
:
- README.md: 书的介绍文字,如前言、简介,在章节中也可做为章节的简介。
readme内容
- SUMMARY.md: 定制书籍的章节结构和顺序。
SUMMARY内容
3、查看本地文件并发布到github
运行命令行gitbook serve
,然后打开浏览器输入localhost:4000
。
网页中查看
我们运行命令行gitbook serve
,会生成文件夹_book
,打开会发现生成是的html等能被浏览器识别的文件,能够部署在服务器或者github中,可以直接上传到github。
4、修改文件
修改目录:目录结构一定要用*
才可以,用其它的符号都不行。
修改目录
然后各自的文件夹里面写各自的章节内容就好了。
最后效果如图所示:
修改后的网页
5、其它配置
项目根目录新建
GLOSSARY.md
,该文件用于词汇、术语列表(可选)。 示例:
## test
测试定义
新建
book.json
文件,里面可以存放一些自定义配置(该文件可选)。
常用的配置选项有:
- title:电子书名
- description:书籍的描述
- author:作者名
- language:本书的语言类型
- direction:文本阅读顺序
常用设置
"plugins": ["expandable-chapters-small"]
开启可折叠目录插件配置
"pluginsConfig": {
"expandable-chapters-small":{}
}
安装和使用可折叠目录插件:(未安装的话,先配置这个,然后可以执行命令gitbook install
进行安装)
安装命令示意图如下:
安装可折叠目录插件
gitbook插件下载地址: https://plugins.gitbook.com/plugin/prism
二、错误解决方案
1、使用
https://github.com/liushilive/gitbook-plugin-books/
出现的错误:
出现的错误
解决方案:
首先下载Katex,如图:
下载katex
如果还不行,就全局安装相应模块npm install -g books-cli
。会首先下载Chromium r609904
如果太慢,建议打开淘宝镜像下载:https://npm.taobao.org/mirrors/chromium-browser-snapshots/Win/609904/
下载到这个目录里面了:C:UsersAdministratorAppDataRoamingnpmnode_modulesbooks-clinode_modulespuppeteer.local-chromium
2、安装过程出现的错误:ERROR: Failed to download Chromium r609904! Set "PUPPETEER_SKIP_CHROMIUM_DOWNLOAD" env variable to skip download.
解决方式:使用国内Chromium源:npm config set puppeteer_download_host=https://npm.taobao.org/mirrors
正常情况如图所示:
下载books-cli
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法