怎么用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预览如下:

Markdown实用语法之实现页面内跳转
1
注意要点:
- []中括号填写需要在页面上显示的内容;
- ()小括号内部声明跳转目标标题,以#开头,标题题号如果包含.、下划线直接忽略掉,标题文本中如果有空格,使用-横杠符号替代,标题文本中的大写字母转换成小写。
小技巧:
对于()小括号内的跳转目标标题,可以将Markdown导出HTML文件,查看HTML源码,用对应标题标签下的id属性值,这样可以保证正确跳转。
怎么用Markdown在github上写书,并用pages展示的更多相关文章
- 写markdown用于Github上readme.md文件
Markdown 文档地址 http://pan.baidu.com/s/1o6nu9To Markdown还有一系列衍生版本,用于扩展Markdown的功能(如表格.脚注.内嵌HTML等等),这些功 ...
- 原来Github上的README.md文件这么有意思——Markdown语言详解
转载请注明出处:http://blog.csdn.net/zhaokaiqiang1992 之前一直在使用github,也在上面分享了不少的项目和Demo,每次创建新项目的时候,使用的都是默认的REA ...
- 【转录】原来Github上的README.md文件这么有意思——Markdown语言详解
之前一直在使用github,也在上面分享了不少的项目和Demo,每次创建新项目的时候,使用的都是默认的README.md文件,也不曾对这个文件有过什么了解.但是在看到别人写的项目的README.md里 ...
- 【Markdown】Writing on Github - 在GitHub上写作
Writing on GitHub https://github.com/shalliestera/Writing-on-GitHub-Chinese-Translation Markdown 基本语 ...
- github上建站和使用markdown写文章
积累了那么久,终于成功搭建了github上的个人网站.虽然方法有点巧妙.不是还是建成了 同时学会用markdown写基本的文章.感觉还可以.附带我的github上的静态页面网站的网址:http://z ...
- 原来Github上的README.md文件这么有意思——Markdown语言详解(sublime text2 版本)
一直想学习 Markdown 语言,想起以前读的一篇 赵凯强 的 博客 <原来Github上的README.md文件这么有意思——Markdown语言详解>,该篇博主 使用的是Mac系统, ...
- GitHub上Markdown语法的高级应用
高级语法格式 本篇的内容来源于Github使用高级格式写作.如果在观看时有什么问题,可以直接查阅源文件.另外需要说明的是Git对Markdown的支持增加了一些扩展功能,因此在Git上可以渲染的Mar ...
- Github上Markdown基本语法
基础写作和语法格式 本篇文章的内容来源于Github的基础写作帮助.如果在观看时有什么问题,可以直接查阅源文件.另外需要说明的是Git对Markdown的支持增加了一些扩展功能,因此在Git上可以渲染 ...
- GitHub上README写法暨markdown语法解读
原文: GitHub上README写法暨markdown语法解读 自从开始玩GitHub以来,就 越来越 感觉它有爱.最近对它的 README.md 文件颇为感兴趣.便写下这贴,帮助更多的还不会编写R ...
随机推荐
- 2019牛客多校第九场B Quadratic equation(二次剩余定理)题解
题意: 传送门 已知\(0 <= x <= y < p, p = 1e9 + 7\)且有 \((x+y) = b\mod p\) \((x\times y)=c\mod p\) 求解 ...
- Node.js & ES Modules & Jest
Node.js & ES Modules & Jest CJS & ESM CommonJS https://en.wikipedia.org/wiki/CommonJS ht ...
- SVG tada 🎉 animation effects
SVG tada animation effects symbol & use <svg viewBox="0 0 80 20" xmlns="http:/ ...
- Android Webview & iframe auto full screen
Android Webview & iframe auto full screen android webview iframe 全屏适配 https://stackoverflow.com/ ...
- css & circle & shapes
css & circle & shapes css-tricks circle https://css-tricks.com/the-shapes-of-css/ https://cs ...
- 「NGK每日快讯」2021.1.15日NGK公链第73期官方快讯!
- Dyno-queues 分布式延迟队列 之 生产消费
Dyno-queues 分布式延迟队列 之 生产消费 目录 Dyno-queues 分布式延迟队列 之 生产消费 0x00 摘要 0x01 前情回顾 1.1 设计目标 1.2 选型思路 0x02 产生 ...
- 020_CSS3
目录 如何学习CSS 什么是CSS 发展史 快速入门 css的优势 三种CSS导入方式 拓展:外部样式两种写法 选择器 基本选择器 层次选择器 结构伪类选择器 属性选择器 美化网页元素 为什么要美化网 ...
- 3分钟学会如何上手supervisor看门狗
软硬件环境 centos7.6.1810 64bit cat /etc/redhat-release #查看系统版本 supervisor 3.4.0 python 2.7.5 supervisor简 ...
- 聊一聊JVM
JVM 什么是JVM? JVM是java虚拟机的缩写,本质上是一个程序,能识别.class字节码文件(.java文件编译后产生的二进制代码),并且能够解析它的指令,最终调用操作系统上的函数,完成我 ...