Introduction
文档
这本书包含GitBook和GitBook.io整个文档。在GitHub允许你改进这个文档。
GitBook是一个工具来构建好的书同时也克使用Git和markdown。你的书可以生成多种格式:
静态网站:这是默认格式,它生成一个完整的交互式静态网站。
PDF:一个完整的PDF和书后的练习解答。
电子书:一个完整的电子书和书后的练习解答。
GitBook是开放源代码的,完全免费,工具的源代码可以在GitHub上。
需要帮助
我们总是乐意帮忙你的书或其他任何你可能有问题。你可以问一个问题或发表在GitHub问题上一个问题或通过电子邮件与我们联系:contact@gitbook.io。
桌面编辑器
一个用于桌面编辑器。它是开放源代码的,可以在GitHub的源代码。
下载
这些平台的编辑器可以下载:
- Windows
- Mac OS
- Linux 32bits
- Linux 64bits
链接你的GitBook.io帐户
你可以容易连接GitBook.io账户通过在身份对话框中输入您的用户名和密码的身份验证对话框:
格式
GitBook的使用规范是在基于markdown文件。
一本书是一个Git存储库包含至少2文件: README.md和SUMMARY.md
README.md
通常情况下,这应该是你的书的介绍。它自动会被添加到最后的总结中。
SUMMARY.md
这个SUMMARY.md定义你的书结构。它应该包含一个章节列表,链接到各自的页面。
例子:
* [English](en/)
* [French](fr/)
* [Español](es/)
文件不包含在SUMMARY.md中将不会被gitbook处理。
多语言
GitBook支持用多种语言编写的书籍。在标准GitBook格式下,每种语言应该是子目录和一个文件命名为LANGS.md应该出现在库的根目录中使用以下格式:
# Summary
This is the summary of my book.
* [section 1](section1/README.md)
* [example 1](section1/example1.md)
* [example 2](section1/example2.md)
* [section 2](section2/README.md)
* [example 1](section2/example1.md)
你可以看到一个完整的示例通过 Learn Git书。
忽略文件和文件夹
GitBook 将阅读.gitignore .bookignore和.ignore 文件,跳过文件和文件夹的列表。(这些文件的格式,和.gitignore一样遵循相同的规范)
发表内容
当你的书是gitbook.io创建的,你需要发表一些内容。
使用编辑器
如果你还没有编辑器,免费安装。
连接你的GitBook.io账户编辑器。您可以使用菜单 Book >Publish 去更新你的书的内容。
使用Git
你可以使用git去发表和更新你的书
$ git push https://push.gitbook.io/{{UserName}}/{{Book}}.git
它将会提示你的用户名(用户名或者邮件)和密码(密码或者api token)
下一步
一旦你把内容发布到GitBook.io,您需要检查您的构建的状态。
构建
通过使用git或者编辑器发布内容后,GitBook.io将开始不同的构建:
网站:它将生成的网站
json:它将提取关于这本书的元数据(摘要、介绍…)
epub:它将生成epub下载
pdf:它将生成pdf下载
构建列表
你书中活动选项卡让你遵循构建的演变
构建细节
当点击构建连接“logs”,你可以访问一个细节页面。本页面将会让你看到构建过程的输出。
修正错误
如果构建失败,您可以使用日志来调试这个问题和发布一个确定的内容。
常见错误
这是一个常见构建错误列表,
Error loading plugins: plugin1, …
这个错误是发生因为Gitbook不能解决一个插件(或插件是无效的)。外部插件需要被指定到node.js 依赖字段中package.json文件。了解更多关于package.json格式。
例如,如果你的书依赖于Autocover插件,您需要一个package.json文件包含以下内容:
{
"name": "mybook",
"version": "0.0.0",
"description": "",
"repository": {
"type": "git",
"url": "https://github.com/Me/mybook.git"
},
"author": "Me ",
"dependencies": {
"gitbook-plugin-autocover": "0.0.5"
}
}
封面
为了让你的书在GitBook.io更加优雅,你可以指定一个封面。
一个封面被指定是cover.jpg文件,一个cover_small.jpg也可以存在作为一个封面更小的版本。封面应该是一个JPEG文件。
合适大小
|
Big |
Small |
File |
cover.jpg |
cover_small.jpg |
Size |
1800x2360 |
200x262 |
自动封面
GitBook插件(autocover)也可以用来生成一个封面文件,或者只是生成cover_small.jpg从你大的封面。
了解更多的自动封面
指南
一个好的封面遵守一下指南:
没有边框
清晰可见的文本标题
在小版本上重要文本也可见
定制域名
在Gitbook.io上所有的书可以通过 http://{{author}}.gitbooks.io/{book}/ . 链接地址访问
不过你也能配置你的书使用一个自定制的域名(一个免费功能在 GitBook.io)
添加一个自定制域名的书过程是很容易的。
1.添加你的域名在你的书中设置.为了使用您自己的域名,你需要改变你的域名注册:
2.登录到你的域名注册和找允许您添加/编辑主机记录部分,经常发现在设置菜单“编辑DNS”,“主机记录”或“区域文件控制”。
3.设置www记录一个CNAME和URL字段设置为:www.gitbook.io。
4.把naked域(yourdomain.com)重定向到www.yourdomain.com,把这个选择指向这个域名。这通常被发现在“转发”,“URL转发”或“URL重定向”。
可能需要几个小时为域名的变化。检查是否准备好或设置与GitBook定制域,输入您的域名(包括www)如下:
可见性
公共/私人
你的书可以公共或私人。公共图书对每个人都可见但只有 collaborators 可以更新它。私人书籍只对 collaborators可见。
你可以把你的书从公共转换私人和从私人到公共。
支付书
书籍只能公共支付。
Home /探索页面
首页和探索页面包含书列表已经成功建造。我们建议设置封面图片。
练习和测试
一本书可以包含互动练习(目前只在Javascript)。是一个代码的挑战提供给读者的练习,这是给定一个代码编辑器编写解决方案,检查对这本书作者的验证代码。
一个练习由4部分组成:
练习留言/目标(在markdown/文本)
初始代码显示给用户,提供一个起点
解决方案的代码,是一个正确的解决方案
验证代码,测试用户的输入的正确性
练习需要开始和完成带有分隔标识(——或* * *)。它应该包含3代码元素(基地,解决方案和验证)。它可以包含第4元素来提供上下文代码(函数,导入库等…不应该显示给用户)。
---
Define a variable `x` equal to 10.
```js
var x =
```
```js
var x = 10;
```
```js
assert(x == 10);
```
```js
// This is context code available everywhere
// The user will be able to call magicFunc in his code
function magicFunc() {
return 3;
}
```
---
测验
一本书可以包含互动测验
在和练习的相同方式下测验也可以被定义
---
Here is the introduction for the quiz
This is Question 1:
- [x] This is the proposition 1 (the correct one)
- [ ] This is the proposition 2
> This is a help message when the answer to question 1 is wrong
This is Question 2:
- [ ] This is the proposition 1
- [x] This is the proposition 2 (correct)
- [x] This is the proposition 3 (correct)
> This is a help message when the answer to question 2 is wrong
---
谷歌Authorship
使用Authorship能提高书籍的搜索结果。
GitBook链接到谷歌作者必须先登录或创建一个Google +概要。
连接你的Google帐户设置。进入关于你G +的页面。
发现底部的“链接”章节。
在章节“链接”有三个选项。“其他配置文件”、“贡献者”,和“链接”。
点击“添加自定义链接”的“贡献者”一节&命名为“GitBook”“标签”字段
Gitbook概要文件的URL添加到URL字段(https://www. gitbook.io/@twitter_username)
点击保存并返回你的G +概要文件