怎么用Markdown在github上写书，并用pages展现

怎么用git写书

安装环境

第一步 安装node npm

先检测本身电脑是否安装了node npm

# 查看 node 版本
    node -v
     
    # 查看 npm 版本
    npm -v
    复制代码

若是成功打印出版本号，说明你本地具有了 node 的运行环境（安装 node 默认安装 npm），而若是没有或报错，则你须要去 node 官网进行 node 的下载及安装，如图：

左边的版本是推荐安装的稳定版本，也就是目前已经被正式列入标准的版本，而右边的版本是当前最新的版本，该版本包含了一些新的特性，还未被彻底列入标准，可能之后会有所变更。这里建议你们安装最新的 node 稳定版进行开发。

第二步 全局安装 gitbook-cli

建议使用 npm 淘宝源：

npm config set registry https://registry.npm.taobao.org/

而后安装gitbook -cli

npm i -g gitbook-cli

第三部 初始化电子书

# 建立一个目录，进入
mkdir gitbook-demo
cd gitbook-demo
 
# 初始化电子书目录
gitbook init 
 
# 编译电子书
gitbook serve 
复制代码

说明一下：

init 之后，目录里会有这两个文件 README.md 和 SUMMARY.md，README.md 是对电子书的简单介绍，SUMMARY.md 是电子书的目录结构。

目录结构长这样：

* [电子书名称](README.md)
* [第一章](chapter1/README.md)
    * [xxxx](chapter1/section1.1.md)
    * [xxxx](chapter1/section1.2.md)
* [第二章](chapter2/README.md)
    * [xxxx](chapter2/section2.1.md)
    * [xxxx](chapter2/section2.2.md)
复制代码

编写 SUMMARY.md，执行 gitbook init 生成目录结构文件，而后编写各个文件夹中生成的文件。

最后 gitbook serve。

gitbook serve 命令实际上会首先调用 gitbook build 编译书籍，完成之后会打开一个 web 服务器，监听在本地的 4000 端口。

若是当前书籍写完了，想要发布到本身的网站的话，也可使用命令输出成html文件使用

gitbook build [书籍路径] [输出路径]

最后搭配git一块儿使用时，只须要在书籍根目录下执行
git init
建立一个git仓库，而后就愉快的拉取-书写-提交循环便可了。

别忘了在提交的时候忽略掉module文件夹，否则每次提交拉取的时候会很痛苦....

图形化编辑管理工具

用一个图形化编辑管理工具，方便咱们实时编辑查看内容，这里推荐用VScode，又能够编辑Markdown，又能够用git，又能够分屏看效果。别忘了在提交的时候忽略掉module文件夹，否则每次提交拉取的时候会很痛苦....
处理VScode中md文件的乱码问题，能够手动生成md文件。不用系统自动生成，这样能够避免乱码

gitbook目录折叠

插件名称：toggle-chapters
效果：默认只在目录导航中显示章的标题，而不会显示小节的标题，点击每一章或者每一节会显示当前章或节的子目录，若是有的话，可是同时会收起其它以前展开的章节。
关于更多的gitbook插件，读者能够参考插件网站。
在根目录(即与SUMMARY.md同级的目录)下的配置文件 book.json(若是没有则新建)中添加插件配置，如图

配置完成后，可按照一下步骤进行：

$ cd gitbook根目录
$ npm install gitbook-plugin-toggle-chapters (此时gitbook的根目录下的node_modules文件夹中已经有了该插件了)
$ gitbook build
$ gitbook serve
访问 http://localhost:4000 看你的插件是否已经生效。

图片使用

能够用博客园的此编辑器，添加图片后发布出来，而后再编辑的时候，就能够看到图片的连接，直接复制到本地编辑器就能够

GitBook源文件发布到gh-pages

复制_book文件下的全部文件，切换到 gh-pages分支，而后将本地编译好的电子书文件（项目根目录下的 _book 目录里的文件 ）上传到这个分支目录下，而后推送、推送玩要编辑仍是要回到master分支

你能够将电子书提交到 github，在托管电子书的仓库建一个 gh-pages 分支，将本地编译好的电子书文件（项目根目录下的 _book 目录里的文件 ）上传到这个分支，而后就可使用这个网址访问 https://liyao0312.github.io/StudyNotes/

固然也能够发布到gitbook，然而这个网站访问有点慢-.-

git checkout --orphan gh-pages
//清空一下分支
rm -rf *
//而后将master分支下的_book静态页面文件内容所有复制到gh-pages分支下
git checkout master -- _book
//将_book中的子文件所有移到外层，并删除_book
mv _book/* ./
rm -rf _book
//这时候gh-pages分支下就是所有的静态页面文件了，接下来就是提交到远程gh-pages分支
git add .
git commit -m 'publish gh-pages'
git push origin gh-pages

GitBook - 安装插件 - 内容折叠功能 - 解决代码过长，影响阅读问题

在 book.json 中 增长下列字段

{
  "plugins": ["accordion"]
}

而后安装

gitbook install

示例模板：

%accordion%Some title here%accordion%

Any content here

%/accordion%

启动gitbook serve预览以下：
![](https://img2018.cnblogs.com/blog/1237308/201908/1237308-20190811222516278-1451482174.png)

Markdown实用语法之实现页面内跳转

1
注意要点:

1. []中括号填写须要在页面上显示的内容；
2. ()小括号内部声明跳转目标标题，以#开头，标题题号若是包含.、下划线直接忽略掉，标题文本中若是有空格，使用-横杠符号替代，标题文本中的大写字母转换成小写。

小技巧：
对于()小括号内的跳转目标标题，能够将Markdown导出HTML文件，查看HTML源码，用对应标题 标签下的id属性值，这样能够保证正确跳转。