轻松打造属于自己的出版平台
发布于 8 年前 作者 imfly 4495 次浏览 来自 分享

声明：这是写给像我这样，需要靠一些工具辅助记忆和总结的人（据统计，这号人占据人类80%，如果，您是那20%的聪明人，就不要在这浪费时间了）

想象一下，一大堆的文档，堆积在不同的文件夹里，没有索引或目录该是多么糟糕的事情。Summary可以让您从这些麻烦中解脱出来，帮您一键生成规范的目录文件，并转化为电子书（html、pdf等格式）。

关于

gitbook-summary(以下简称Summary）是一个自动构建目录的小工具。这是命令行工具的中文文档，也是它的Demo工程（这里有删减）。

电子书地址

源文地址

（这里省略xxx字）

Summary的安装

安装很简单，大致流程如下：

如果没有安装nodejs，请先安装它，参考这里： https://cnodejs.org/topic/5338c5db7cbade005b023c98

安装Summary

命令：

$ npm install -g gitbook-summary

Summary的使用

具体的使用方法也是简单到一条命令即可

首先，打开命令行；然后，进入书目所在目录，键入如下命令

$ book sm g

一个完整的目录文件SUMMARY.md就生成了。当然，您可能并不满意，接着往下看。

规划目录结构

Summary默认将文件夹作为章节名称，文件夹嵌套对应目录结构，如果愿意，您可以无限嵌套。

这样做，有很多好处，首先，把每一章的主题抽象为一个文件夹，然后把各章节独立成一个文件，放在该文件夹下，层次清晰，维护方便；其次，针对每一个概念，可以按照“面向对象”编程的思维去拆分，去写作。

像这样：

源文件夹（how-to-create-self-publishing-platform）
├── 干嘛要写书？   
├───── 写书的必要性 
├───── 写书的好处  
...
├── 如何打造自己的平台？
├───── Summary的安装
├───── Summary的使用 
├───── 电子书的生成 
├───── 电子书的发布
...
└── README.md

调整目录顺序

内容是有先后逻辑的。Summary，默认按照章节（文件夹）的字母顺序排列。如果，您不满意，可以在前面加上字母或数字， 具体格式是:

{数字或字母}-文件夹或文件名称

注意：不要使用_下划线。这里标识的仅是顺序，并不显示在电子书里，因此建议使用数字，修改相对方便些。

像这样：

源文件夹
├── 1-干嘛要写书？ 
├───── 1-写书的必要性 
├───── 2-写书的好处
├── 2-什么是即时出版平台？
├───── readme.md
├── 3-如何打造自己的平台？
├───── 1-Summary的安装
├───── 2-Summary的使用 
├───── 3-电子书的生成 
├───── 4-电子书的发布
...
└── README.md

隐藏某些章节

默认，出现在SUMMARY.md的章节，电子书中都有显示，只不过，如果文章不存在，该章节将呈灰度状态，无法点击，这样让读者能看到书目整体结构，对作者有进一步的期待。

相反，没出现在SUMMARY.md的文章，最终生成的电子书是看不到的（隐藏的）。可以命令：

在命令行，进入书目目录

$ book sm g -i 0home, 1-干嘛要写书

-i 是参数 --ignores 的缩写形式，意思是忽略该参数提供的目录。与它相对的有另一个参数-c，即--catalog，是指全部要显示的目录，这两个参数可以同时使用，不过，显然不能同时包含同一个目录。命令：

$ book sm g  -c 2-什么是即时出版平台？, 3-如何打造自己的平台？

具体有那些参数可用，可以这样查看：

$ book sm g -h

启用配置文件

使用这些参数，每次都要输入，还是有很多不便。Summary默认支持用book.json配置书籍基本信息，格式如下：

{
    "bookname": "json-config-name",
    "outputfile": "test.md",
    "catalog": "all",  // 如 [chapter1，chapter2, ...]
    "ignores": [], 
    "unchanged": [] // 如: ['myApp'] -> `myApp` not `My App` 
}

需要把这个文件放在书目的根目录（顶层），当然，也可以提供更多内容，Summary建议您这么做（下一版本，会提供一个简单的命令，自动生成这个文件）。然后，您就可以简单的:

$ book sm g

这样就获得一个 test.md 目录文件（测试时用其他名字，不会覆盖原SUMMARY.md）。

其他更好玩的

比如，如果把文件命名为"readme.md"、“Readme.md”或“README.md”，它将自动链接到它所在的目录上（该目录就是可点击的）

更直观的，看看本书的源码结构吧。

电子书的生成

如何生成电子书，这里需要另一个工具Gitbook（下一版本，Summary会集成它）

Gitbook也是一个命令行工具，用于build book，可以把Markdown文件转成HTML、PDF等多种格式电子书，并提供了一个同名的平台（gitbook.io），可以发布和销售电子书。

Gitbook提供了Git相关管理功能（因此才有了Git前缀），管理原始文档有了诸多选择，这就是它的魅力。

安装Gitbook

$ npm install  -g  gitbook

构建电子书

运行下面的命令之前，要先使用Summary生成一个’SUMMARY.md’，然后，在书目录下，运行：

$ gitbook build

这将把所有.md文件，转换成.html格式的静态文件，并存放在根目录下的_book目录。因为是静态文件，通常可以进入该目录直接点击index.html文件，从浏览器中看到效果。另外，也可以，用下面的命令：

$ gitbook serve

该命令，在构建的基础上，启动一个HTTP Server运行。打开浏览器，在地址栏输入 http://localhost:4000 就可以访问生成的电子书了。其中位于左侧书目顶部的Introduction一节就编译自README.md，目录编译自SUMMARY.md。

要在自己的网站上发布新书，只需把_book目录复制到服务器相应目录即可。

更酷的功能

Gitbook支持将一些外部的JavaScript文件嵌入到HTML中，例如Google统计、Disqus评论系统等。下面，以页面中嵌入Disqus评论为例。

1> 首先，安装Disqus插件

$ npm install gitbook-plugin-disqus

2> 然后，在book.json文件里，添加下面的内容：

{
  "plugins": ["disqus"],
  "pluginsConfig": {
    "disqus": {
      "shortName": "你在Disqus上的项目名"
    }
  }
}

3> 最后，运行命令：

$ gitbook serve

刷新浏览器，即可看到附加了Disqus评论的页面。

电子书的发布

Gitbook提供了一个发布平台Gitbook.com。这个平台应该也是它未来盈利和发展的目标，可惜在国内访问有些慢，另外体验也不是很好。因此，我们选择使用github pages作为发布书目的替代方案。

Github Pages的特点

  1. 使用简单；

  2. 全部免费；

  3. 支持静态脚本，支持DIY；

  4. 可以绑定自己的域名，功能不差

操作方法

1. 两种Pages模式的选择

github pages支持两种模式，一种是User & Organization Pages(用户和组织页），另一种是Project Pages（工程页）。

1> 用户和组织页，通常作为一个独立的工程存在，目的是介绍作者或组织的目标、产品等信息，直接托管在master分支就可以，维护方便。

2> 工程页，重在宣传项目、提供demo或api文档，是工程的辅助，需要托管在gh-pages分支。

我们建议把书目当作工程管理，因此使用Project Pages（工程页），如果你建立一个组织，就可以把各类书目集中到该User & Organization Pages(用户和组织页）里（而每本书还是用的工程页）。

2.发布电子书

我们就以本书为例，采取手动发布到Project Pages（工程页）的方式（请看[官方文档][1]）：

1> 建立一个干净的分支

所谓的干净，就是没有其他分支的历史信息(也叫"orphan"分支），最好是直接克隆

$ git clone https://github.com/imfly/how-to-create-self-publishing-platform.git

2> 建立gh-pages分支

同时，要删除所有文件

$ cd how-to-create-self-publishing-platform

$ git checkout --orphan gh-pages

$ git rm -rf .

3> 添加内容，上传

现在，可以将使用gitbook build生成的目录_book下的文件，手动拷贝到该分支里，然后：

$ git add --all
$ git commit -m "All book pages commit"
$ git push origin gh-pages

打开浏览器，输入地址 http(s)://<username>.github.io/<projectname> ，这里就是 http://imfly.github.io/how-to-create-self-publishing-platform （记住是.io而不是.com)，电子书已经可以浏览了。

至于，定制使用自己的域名，请看官方文档吧。

最佳实践

写书，跟写代码一样，是个体力活。 妙手偶得，无须刻意。

选择写作时机

本书，如果也能当作书（我个人确实是把它当做书来写的 ^_^）的话，这么点内容，我用了整整2天，大概10多个小时。如果，再长一些，就我个人而言，肯定是坚持不住的，因此，这样集中去写，应该不是最好的实践（当然，那些专业写手，可能恰恰相反）。

我仅仅酷爱技术，管理、写东西，都是副产品。所以，我个人提倡在写代码之余，或者在查资料、解决问题的同时，将有价值的东西，集中的、分门别类的放在一起，最后，用点时间集中整理一下就是了。

说实话，本书如果从零开始，2天时间，我根本完不成，很多东西，也都是早就有了初步想法和相关资料的。

真正行动起来

知识是要靠时间积累的。虽然，我们不提倡刻意去写，但要求刻意去积累。哪怕是一个小小的问题，一定要记下来。找到了答案，怎么解决的，一定要简单的回忆和总结出来。要求不用很高，但要行动。

这个习惯，我和团队，保持了多年。虽然，我们不是什么成功人士、技术大咖，但是这让我们积累了知识，降低了沟通成本。

约束优于配置

生活是相通的。所谓的“约束优于配置”，用在工作和生活中，只不过是把规律化的东西习惯化、定势化而已。无论做什么，只要打开电脑，我一定会默认打开一个专门文件夹，随手记下相关信息。

我天生就是懒人，仅仅是因为积累的东西太多、太乱，整理修改繁琐，索性就写了Summary这个小工具出来。如果能对小盆友们有用，欣喜至极，不然，请拍砖。

增量开发写作

写代码的人都知道，没有谁一下子就能把代码写得很漂亮，迭代是必需的。也不可能一次就把各种功能都写出来，增量开发是必然的。写作也是如此，因为我们没有明确的功利驱动，便有更多时间和机会去迭代，去增量写作。

每天坚持写一点，几年下来，你会非常惊讶自己的。

关于作者

Imfly，把快乐作为一切取舍的唯一考量。感念生命短促，希望通过技术结识更多小伙伴，做更多自己喜欢、擅长、有价值的事情。

微信：kubying

参考信息

回到顶部