diff options
| -rw-r--r-- | docs/README.md | 2 | ||||
| -rw-r--r-- | docs/SUMMARY.md | 10 | ||||
| -rw-r--r-- | docs/internals/README.md | 33 | ||||
| -rw-r--r-- | docs/internals/api.md | 59 | ||||
| -rw-r--r-- | docs/internals/browser.md | 37 | ||||
| -rw-r--r-- | docs/setup.md | 24 |
6 files changed, 148 insertions, 17 deletions
diff --git a/docs/README.md b/docs/README.md index 272896d..781f2aa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# GitBook Toolchain Documentation + This document aims to be a comprehensive guide to GitBook. It contains the full documentation for version **{{ book.version }}**. Help for GitBook.com specific questions can be found at [help.gitbook.com](https://help.gitbook.com). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e3d8d67..7cb21f0 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -44,10 +44,16 @@ ### Plugin Development -* [Introduction](./api/README.md) -* [Node](./api/node.md) +* [Creating a plugin](./api/README.md) * [Connect to the context](./api/connect.md) * [Components](./api/components.md) +* [Node APIs](./api/node.md) + +### Internals + +* [Using programmatically](./internals/README.md) +* [Browser environment](./internals/browser.md) +* [APIs](./internals/api.md) -- diff --git a/docs/internals/README.md b/docs/internals/README.md new file mode 100644 index 0000000..7ee13c3 --- /dev/null +++ b/docs/internals/README.md @@ -0,0 +1,33 @@ +# Using GitBook programmatically + +GitBook is mainly designed to work as a command line utility, but it can also be integrated into javascript application (Node.js or browser). + +Its API can be used for parsing a book, modifying the structure of a book, or generating outputs. + +### Installation + +``` +$ npm install gitbook +``` + +### Design + +The GitBook Core API is built around **promises** and **immutable** models. + +### Example + +```js +const GitBook = require('gitbook'); + +// Create a filesystem interface +const fs = GitBook.createNodeFS(__dirname + '/mybook'); + +// Create a book instance +const book = GitBook.Book.createForFS(fs); + +// Parse it +GitBook.Parse.parseBook(book) +.then(newBook => { + console.log('Done!'); +}) +``` diff --git a/docs/internals/api.md b/docs/internals/api.md new file mode 100644 index 0000000..0077adc --- /dev/null +++ b/docs/internals/api.md @@ -0,0 +1,59 @@ +# APIs + +- [Parsing](#parsing) +- [Manipulation](#manipulation) +- [Generation](#generation) + +## Parsing + +### `GitBook.Parse.parseBook` +`GitBook.Parse.parseBook(book: Book): Promise<Book>` + +Parse the whole book (languages, readme, summary), it returns a complete version of the book instance. + +### `GitBook.Parse.parse[Summary|Glossary|Languages]` +`GitBook.Parse.parse[X](book: Book): Promise<Book>` + +Parse a specific part of the book only, it returns a book instance with the updated part. + +These methods can be used in combinaison with a file watch to avoid parsing the whole books when a file is modified. + +## Manipulation + +### `GitBook.SummaryModifier.toText` +`GitBook.SummaryModifier.toText(summary: Summary, fileExt: String?): String` + +Serialize the summary as a string, the argument `fileExt` can be used to specify the parser: + +```js +const textDefault = GitBook.SummaryModifier.toText(summary); +const textAdoc = GitBook.SummaryModifier.toText(summary, '.adoc'); +const textAdoc = GitBook.SummaryModifier.toText(summary, '.md'); +``` + +### `GitBook.SummaryModifier.insertArticle` +`GitBook.SummaryModifier.insertArticle(summary: Summary, article: Article, level: String): Summary` + +Insert a summary `article` after the article identified with `level`. + +### `GitBook.SummaryModifier.unshiftArticle` +`GitBook.SummaryModifier.unshiftArticle(summary: Summary, article: Article): Summary` + +Insert a summary `article` at the beginning of it. + +### `GitBook.SummaryModifier.removeArticle` +`GitBook.SummaryModifier.removeArticle(summary: Summary, article: Article|String): Summary` + +Remove an article from the summary. + +## Generation + +### `GitBook.Output.getGenerator` +`GitBook.Output.getGenerator(type: String): Generator` + +Return a generator, `type` may be one of `["website", "json", "ebook"]`. + +### `GitBook.Output.generate` +`GitBook.Output.generate(generator: Generator, book: Book): Output` + +Generate a book using a generator. diff --git a/docs/internals/browser.md b/docs/internals/browser.md new file mode 100644 index 0000000..1ea51bb --- /dev/null +++ b/docs/internals/browser.md @@ -0,0 +1,37 @@ +# Parsing GitBook in the browser + +The GitBook core API can be integrated in applications running in a browser environment (web application or Electon). One good example is the official [GitBook Editor](https://www.gitbook.com/editor), built using Electon and the GitBook core library. + +The `gitbook` package can be imported during a browserify/webpack build. Only the parsing components will be bundled. **Generating an output** is not possible on a browser environment. + +### Mocking the filesystem + +Since books are a composition of multiple files in a directory, the parsing requires some kind of filesystem interface. + +On a node.js environment, GitBook provides a method to create the right interface: `GitBook.createNodeFS(bookFolder: String): FS`. + +On a browser application, the interface depends mostly on your application design. + +```js + +const appFS = GitBook.FS.create({ + // (String): Boolean + fsExists(filePath) { + ... + }, + // (String): Buffer + fsReadFile(filePath) { + ... + }, + // (String): { mtime: Date } + fsStatFile(filePath) { + ... + }, + // (String): Array<String> + fsReadDir(filePath) { + ... + } +}); +``` + +[Checkout the core FS interfaces](https://github.com/GitbookIO/gitbook/tree/master/packages/gitbook/src/fs) for greater example. diff --git a/docs/setup.md b/docs/setup.md index 9300678..ce5e0ca 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2,24 +2,18 @@ Getting GitBook installed and ready-to-go should only take a few minutes. -### GitBook.com +This page describe the process for running the toolchain locally. The easiest for writing and hosting your content is to use [GitBook.com](https://www.gitbook.com) and the [GitBook Editor](https://www.gitbook.com/editor). -[GitBook.com](https://www.gitbook.com) is an easy to use solution to write, publish and host books. It is the easiest solution for publishing your content and collaborating on it. - -It integrates well with the [GitBook Editor](https://www.gitbook.com/editor). - -### Local Installation - -##### Requirements +### Requirements Installing GitBook is easy and straightforward. Your system just needs to meet these two requirements: -* NodeJS (v4.0.0 and above is recommended) +* Node.js (v4.0.0 and above is recommended) * Windows, Linux, Unix, or Mac OS X -##### Install with NPM +### Install with NPM -The best way to install GitBook is via **NPM**. At the terminal prompt, simply run the following command to install GitBook: +The best way to install GitBook is via **NPM** (or **Yarn**). At the terminal prompt, simply run the following command to install GitBook: ``` $ npm install gitbook-cli -g @@ -27,7 +21,7 @@ $ npm install gitbook-cli -g `gitbook-cli` is an utility to install and use multiple versions of GitBook on the same system. It will automatically install the required version of GitBook to build a book. -##### Create a book +### Create a book GitBook can setup a boilerplate book: @@ -37,6 +31,8 @@ $ gitbook init If you wish to create the book into a new directory, you can do so by running `gitbook init ./directory` +### Preview your website + Preview and serve your book using: ``` @@ -49,7 +45,7 @@ Or build the static website using: $ gitbook build ``` -##### Install pre-releases +### Install pre-releases `gitbook-cli` makes it easy to download and install other versions of GitBook to test with your book: @@ -59,7 +55,7 @@ $ gitbook fetch beta Use `gitbook ls-remote` to list remote versions available for install. -##### Debugging +### Debugging You can use the options `--log=debug` and `--debug` to get better error messages (with stack trace). For example: |