轻松打造属于自己的出版平台
发布于 7 年前 作者 imfly 4012 次浏览 最后一次编辑是 6 年前 来自 分享

声明:这是写给像我这样,需要靠一些工具辅助记忆和总结的人(据统计,这号人占据人类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

参考信息

回到顶部