文档章节

用 Github、Markdown 和 GitBook 写开源书

waylau
 waylau
发布于 2014/12/11 21:25
字数 575
阅读 11001
收藏 34

原文同步至:http://www.waylau.com/using-github-markdown-gitbook-write-open-source-books/

之前一直是在 Github 上写开源书(见:http://www.waylau.com/books/)但,由于 Github 本身的目录结构并不一定符合阅读的习惯,而且没有提供 pdf , ePUB, MOBI 等格式的转换下载。很多同学也还是习惯离线看文档。GitBook 就是解决这一问题。

GitBook 让你在保持在 Github 的书写习惯外,稍加配置,就能自动发布到GitBook 上,形成界面漂亮的电子书了(支持 html, pdf , ePUB, MOBI 等)。

<!-- more -->

如果你是第一次使用 GitBook,可以参见 使用 GitBook 写开源书

下面介绍,如果将一个 Github 项目转移到 GitBook 上来

##注册账户

需要拥有 GithubGitBook 的账户

##关联账号

将 GitBook 的项目关联上 Github 的库

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/09_zpsaeaf67fe.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/09_zpsaeaf67fe.jpg" border="0" alt=" photo 09_zpsaeaf67fe.jpg"/></a>

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/10_zpsedcdd57a.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/10_zpsedcdd57a.jpg" border="0" alt=" photo 10_zpsedcdd57a.jpg"/></a>

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/15_zps799c92ae.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/15_zps799c92ae.jpg" border="0" alt=" photo 15_zps799c92ae.jpg"/></a>

##原有的项目

这个是原来的项目结构,参见https://github.com/waylau/apache-shiro-1.2.x-reference

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/01_zpscf15bb6f.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/01_zpscf15bb6f.jpg" border="0" alt=" photo 01_zpscf15bb6f.jpg"/></a>

##添加 SUMMARY.md 文件配置

不改变原有的项目结构,添加 SUMMARY.md 文件,描述了 GitBook 目录结构,如下:

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/03_zpsc08a9a83.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/03_zpsc08a9a83.jpg" border="0" alt=" photo 03_zpsc08a9a83.jpg"/></a>

# Summary

This is the summary of my book.

* I. Overview 总览
	* [1. Introduction 介绍](I. Overview 总览/1. Introduction 介绍.md) 
	* [2. Tutorial 教程](I. Overview 总览/2. Tutorial 教程.md) 
	* [3. Architecture 架构](I. Overview 总览/3. Architecture 架构.md) 
	* [4. Configuration 配置](I. Overview 总览/4. Configuration 配置.md) 
* II. Core 核心
	* [5. Authentication 认证](II. Core 核心/5. Authentication 认证.md) 
	* [6. Authorization 授权](II. Core 核心/6. Authorization 授权.md) 
* III. Web Applications
* IV. Auxiliary Support 辅助支持
* V. Integration 整合
* VI. Tools 工具
* VII. Index 目录
* VIII. Other 其他

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/02_zps4c051456.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/02_zps4c051456.jpg" border="0" alt=" photo 02_zps4c051456.jpg"/></a>

##编译

$ gitbook build ./

编译成功后,生成 _book 目录

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/04_zps2c62f5e9.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/04_zps2c62f5e9.jpg" border="0" alt=" photo 04_zps2c62f5e9.jpg"/></a>

##运行

运行 _book 目录 中 的index.html

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/05_zps05da7c9e.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/05_zps05da7c9e.jpg" border="0" alt=" photo 05_zps05da7c9e.jpg"/></a>

效果

<a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/06_zpsf5ef9805.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/06_zpsf5ef9805.jpg" border="0" alt=" photo 06_zpsf5ef9805.jpg"/></a>

##提交更新到 Github,自动发布到 GitBook

提交代码到 Github 的库,由于 GitBook 的项目关联上 Github 的库,所以 GitBook 会自动根据 Github 进行发布。 效果如下: <a href="http://s1288.photobucket.com/user/waylau/media/waylau%20blog/gitbook/16_zpsae785ba0.jpg.html" target="_blank"><img src="http://i1288.photobucket.com/albums/b484/waylau/waylau%20blog/gitbook/16_zpsae785ba0.jpg" border="0" alt=" photo 16_zpsae785ba0.jpg"/></a>

在线电子书:http://waylau.gitbooks.io/apache-shiro-1-2-x-reference/

© 著作权归作者所有

共有 人打赏支持
waylau

waylau

粉丝 503
博文 92
码字总数 165544
作品 2
深圳
架构师
私信 提问
加载中

评论(3)

waylau
waylau

引用来自“金三胖”的评论

引用来自“waylau”的评论

擦~ 图怎么都挂了。可以看这里 http://www.waylau.com/using-github-markdown-gitbook-write-open-source-books/

你给的地址也打不开,在这里把图片补一下吧
可以打开啊,。多刷新几次,今晚上的服务器貌似有些不稳定
金三胖
金三胖

引用来自“waylau”的评论

擦~ 图怎么都挂了。可以看这里 http://www.waylau.com/using-github-markdown-gitbook-write-open-source-books/

你给的地址也打不开,在这里把图片补一下吧
waylau
waylau
擦~ 图怎么都挂了。可以看这里 http://www.waylau.com/using-github-markdown-gitbook-write-open-source-books/
Gitbook,这个开源出书平台了不起

“程序猿”常常戏称,GitHub 是全球最大的同性交友网站。 只不过,在 GitHub 上交友十分特别,你可以浏览别人在上面托管的项目、代码,通过 Issue 这个功能反馈意见,与项目开发者讨论,还可...

oschina
2015/12/26
17.1K
30
docsify 不一样的文档工具

一、无规范不和谐 俗话说"无规矩不成方圆",但是我要说无规范不和谐,你可能觉得言重了「言重个毛」,下面就简单的说一下吧 公司没有规范可以吗「那不乱了套了」 人事招人没有规范可以吗「随...

TigerChain
11/06
0
0
markdown 文档转 html 工具 - mddoc

mddoc 是一个开源的 markdown 文档转 html 文档工具,它使用 php 开发,支持 php >= 5.4。它生成的 html 可以直接放在网站上,支持全文搜索、自定义 html 模版。 mddoc 同时支持命令行、git...

宇润
06/27
0
0
GitBook快速教程 2.2 目录页和普通页

版权声明:本文为twowinter原创文章,请联系微信公众号twowinter,未经博主允许不得转载。 https://blog.csdn.net/iotisan/article/details/81121263 这是一个 gitbook 教程,介绍如何基于模...

iotisan
07/19
0
0
使用Asciidoc代替Markdown和Word撰写开发文档

开发文档一般都由Word或Markdown(格式)撰写,前则多见于企业项目,后则在开源界很流行。但在实际使用中总觉得不尽人意。 他们的不是 Word的问题 表现上:格式过于复杂,导致写出来的文档排...

孤岛旭日
2015/10/30
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Java面试题:面向对象,类加载器,JDBC, Spring 基础概念

1. 为什么说Java是一门平台无关语言? 平台无关实际的含义是“一次编写到处运行”。Java 能够做到是因为它的字节码(byte code)可以运行在任何操作系统上,与底层系统无关。 2. 为什么 Java...

Java干货分享
14分钟前
0
0
LeetCode算法题-Range Sum Query Immutable(Java实现)

01 看题和准备 今天介绍的是LeetCode算法题中Easy级别的第70题(顺位题号是303)。给定整数数组nums,找到索引i和j(i≤j)之间的元素之和,包括端点。例如: 给定nums = [-2,0,3,-5,2,-1] s...

qwergkp
19分钟前
0
0
慎用延时初始化(71)

延迟初始化是延时到需要域的值的时候才进行初始化 如果不需要,永远不初始化 既适用于静态域、也适用于实例域 延时初始化是一种优化 除非绝对必要,请尽量不要使用 降低了初始化开销、增加了...

Java搬砖工程师
20分钟前
1
0
中介者模式 调停者 Mediator 行为型 设计模式(二十一)

  用一个中介对象(中介者)来封装一系列的对象交互,中介者使各对象不需要显式地相互引用,从而使其耦合松散      而且可以独立地改变它们之间的交互。      中介者模式又称为调停...

SEOwhywhy
30分钟前
4
0
大数据Spark优化读取Hbase--region 提高并行数过程详细解析

一. Hbase 的 region 我们先简单介绍下 Hbase 的 架构和 region : 从物理集群的角度看,Hbase 集群中,由一个 Hmaster 管理多个 HRegionServer,其中每个 HRegionServer 都对应一台物理机器...

金铭鼎IT教育
30分钟前
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部