Summary的使用

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

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

$ book sm

一个完整的目录文件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 -i 0home, 1-干嘛要写书

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

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

具体有那些参数可用,可以这样查看:

$ book -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

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

其他更好玩的

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

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