Gitbook文档翻译

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应该出现在库的根目录中使用以下格式:

# SummaryThis 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 <me@gmail.com>","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 quizThis 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 wrongThis 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 +概要文件