• Stars
    star
    101
  • Rank 330,361 (Top 7 %)
  • Language
    JavaScript
  • Created over 8 years ago
  • Updated almost 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

CLI to convert an existing document to a GitBook.

gitbook-convert

NPM version

CLI to convert an existing document to a GitBook.

Install

Install this globally and you'll have access to the gitbook-convert command anywhere on your system.

$ npm install gitbook-convert -g

Use

$ gitbook-convert [options] <file> [export-directory]

Options

Short Long Description Type Default
-t --document-title Name used for the main document title string null
-a --assets-dir Name of the document's assets export directory string assets
-m --max-depth Maximum title depth to use to split your original document into sub-chapters integer 2
-p --prefix Prefix filenames by an incremental counter flag false
-d --debug Log stack trace when an error occurs flag false

After converting your document, the corresponding GitBook files will be placed in the provided export-directory folder. The folder is created during conversion.

If export-directory is not provided, a new export folder is created in the current working directory. The GitBook files are then placed here.

If the --document-title argument is not passed, the filename without the file extension will be used as the main document title.

Currently accepted formats

Type Extension
Microsoft Office Open XML Document .docx
OpenOffice / Open Document Format .odt
Docbook Markup Language .xml
HyperText Markup Language .html

Output

This version of gitbook-convert generates markdown files only. Support for asciidoc might be added later.

Document processing

gitbook-convert divides your original document into chapters and sub-chapters, if any, one per output file. To do this, gitbook-convert automatically detects the headers in your document and uses the -m flag to split it into sub-chapters.

When converting a Docbook file though, the depth is always detected automatically.

Thus, converting the following document named History of modern computers.docx with the default --max-depth flag:

Chapter 1

What the world used to be.

The beginning

At the beginning was the big bang...

The following

Strange creatures called โ€œhumansโ€ had trouble living in peace...

Chapter 2

What the world is now.

The awakening

Computers came to rule the world...

The end

The power supply went disconnected.

will produce the following output:

user @ cwd/export/history_of_modern_computers
  README.md
  SUMMARY.md
  assets/
  chapter_1/
    README.md
    the_beginning.md
    the_following.md
  chapter_2/
    README.md
    the_awakening.md
    the_end.md

While using 1 for --max-depth would produce:

user @ cwd/export/history_of_modern_computers
  chapter_1.md
  chapter_2.md
  README.md
  SUMMARY.md
  assets/

Summary

The SUMMARY.md file is created automatically.

For our first example:

# Summary

* [Introduction](README.md)
* [Chapter 1](chapter_1/README.md)
  * [The beginning](chapter_1/the_beginning.md)
  * [The following](chapter_1/the_following.md)
* [Chapter 2](chapter_2/README.md)
  * [The awakening](chapter_2/the_awakening.md)
  * [The end](chapter_2/the_end.md)

With --max-depth set to 1:

# Summary

* [Introduction](README.md)
* [Chapter 1](chapter_1.md)
* [Chapter 2](chapter_2.md)

README

The content of the README.md file depends on your document structure. Anyways, the filename of your original document will be used as the main title here.

Original document starts with a main header

gitbook-convert creates the default GitBook README.md file:

# History of modern computers

This file serves as your book's preface, a great place to describe your book's content and ideas.
Original document has an introduction

Otherwise, everything before the first main header is used as the README.md content. If we modify our example to be:

A short history of modern computers.

Chapter 1

The beginning

At the beginning was the big bang...

The following

...

The content of the README.md file will be:

# History of modern computers

A short history of modern computers.

The behavior is the same when --max-depth is set to higher levels. Each README.md in the sub-chapters folders will contain the preface for the current chapter.

Converters

The appropriate converter for a document type is deduced from its extension.

For now, the converters should:

  • be placed in lib/converters,
  • with its filename being the document-type extension, for example /lib/converters/docx.js,
  • added to the lib/converters/index.js file for reference and use.

docx

The .docx converter uses mwilliamson's mammoth.js to convert your document to HTML before generating the output.

gitbook-convert will try to export your inline images in the /assets folder, using the image title as the image filename if provided.

odt

The .odt converter uses odt2html to convert your document to HTML before generating the output. Because there was no node module out there to convert OpenOffice documents to HTML, we built our own.

gitbook-convert will try to export your inline images in the /assets folder, using the image name in the document as the image filename if provided.

docbook

gitbook-convert requires xsltproc to be installed to process a Docbook. If you are using MacOS or a Linux distribution, it should be installed by default.

You can test that xsltproc is installed using:

$ which xsltproc

xsltproc uses the last version of docbook.xsl to convert your Docbook to HTML first. Since the Docbook XML markup is very large, gitbook-convert will try to convert the meta-data as well as possible. Extended conversion might be added to the tool based on user requests.

When you install gitbook-convert using npm, the docbook.xsl stylesheets are downloaded and installed along with the app.

We recommend using the tool with Docbook version 5. Here is a walk-through for converting an existing Docbook in version 4 to version 5.

More Repositories

1

gitbook

The open source frontend for GitBook doc sites
TypeScript
26,513
star
2

javascript

GitBook teaching programming basics with Javascript
3,322
star
3

nuts

๐ŸŒฐ Releases/downloads server with auto-updater and GitHub as a backend
JavaScript
1,242
star
4

gitbook-cli

GitBook's command line interface
JavaScript
707
star
5

git

ProGit Book Fork generated using GitBook
306
star
6

markup-it

JavaScript library to parse and serialize markup content (Markdown and HTML)
JavaScript
268
star
7

markdown

Learn how to use Markdown
242
star
8

kramed

A markdown (kramdown compatible) parser and compiler. Built for speed. (Fork of marked)
HTML
224
star
9

theme-default

Default theme for GitBook
JavaScript
195
star
10

rousseau

Lightweight proofreader in JS
JavaScript
179
star
11

theme-api

Theme for publishing a beautiful API documentation with GitBook
JavaScript
150
star
12

community

GitBook's official community page
107
star
13

slate-edit-table

Slate plugin for table edition
JavaScript
101
star
14

slate-edit-list

A Slate plugin to handle keyboard events in lists.
JavaScript
94
star
15

proxies-on-cloudflare

Proxies in Cloudflare Workers
TypeScript
93
star
16

plugin-mathjax

MathJAX plugin for GitBook
JavaScript
89
star
17

plugin-autocover

Generate a cover for the book
JavaScript
87
star
18

styleguide

GitBook.com HTML/CSS Style Guide
JavaScript
86
star
19

repofs

Simple and unified API to manipulate Git repositories
JavaScript
77
star
20

hunspell-spellchecker

Parse and use Hunspell dictionaries in Javascript
JavaScript
77
star
21

micro-analytics

A micro multi-website analytics database service designed to be fast and robust, built with Go and SQLite.
Go
76
star
22

plugin

Sample plugin for GitBook
JavaScript
66
star
23

integrations

Toolkit to build integrations on GitBook
TypeScript
62
star
24

filterable

Parse and convert GitHub-like search queries in Node.JS
JavaScript
61
star
25

example

Simple GitBook example
59
star
26

plugin-katex

Math typesetting using KaTex
JavaScript
59
star
27

plugin-exercises

Interactive exercices in a gitbook
JavaScript
56
star
28

react-rich-diff

React component to render rich diff between two documents (Markdown, HTML)
JavaScript
52
star
29

plugin-disqus

Disqus comments on your books
JavaScript
51
star
30

plugin-ga

Google Analytics tracking for your book
JavaScript
51
star
31

git-sync-normalization

A repository that shows how we translate every content block to markdown.
50
star
32

slate-edit-code

A Slate plugin for code block editing
JavaScript
43
star
33

theme-faq

Theme for publishing a FAQ or Knowledge base
HTML
38
star
34

node-gitbook-api

Node client library for the GitBook API
JavaScript
36
star
35

plugin-youtube

Plugin to insert youtube videos in a GitBook
JavaScript
33
star
36

tokenize-text

Javascript text tokenizer that is easy to use and compose.
JavaScript
30
star
37

slate-prism

A Slate plugin to highlight code blocks using PrismJS
JavaScript
27
star
38

plugin-quizzes

Interactive quizzes in a gitbook
JavaScript
26
star
39

plugin-search

Search content in your book
JavaScript
25
star
40

plugin-codetabs

Multiple languages code blocks for GitBook
JavaScript
25
star
41

plugin-algolia

Power search using Algolia
JavaScript
25
star
42

theme-official

GitBook theme for our own books
HTML
25
star
43

go-gitbook-api

GitBook API client in GO (golang)
Go
24
star
44

plugin-github

Display a link to your GitHub repo in your gitbook
JavaScript
24
star
45

slate-hyperprint

A library to convert Slate models to their slate-hyperscript representation
JavaScript
24
star
46

plugin-hints

GitBook plugin. Defines 4 types of styled hint blocks: info, danger, tip, working
JavaScript
23
star
47

expect-firestore

API client and Jasmine matchers for the Firestore Rules API
JavaScript
22
star
48

plugin-puml

UML Diagrams rendering using PlantUML
JavaScript
21
star
49

go-github-webhook

A GitHub webhook handler written in Go
Go
21
star
50

node-opds

Node.js library to parse/generate OPDS feed
JavaScript
21
star
51

plugin-comment

Inline discussions integrated with gitbook.com
JavaScript
20
star
52

node-onix

Node.JS library to parse/generate ONIX XML files
JavaScript
18
star
53

slate-sugar

๐Ÿญ Create Slate documents using JSX.
JavaScript
17
star
54

bipbip

Benchmark runner for performance regression test suites
JavaScript
17
star
55

slate-lite-renderer

Fast renderer for read-only Slate documents
JavaScript
16
star
56

plugin-fontsettings

Font settings for GitBook website
CSS
16
star
57

github-api-signature

Node.js signature generator for GitHub API using a PGP key
TypeScript
15
star
58

isbn-utils

Javascript utilities to parse and normalize ISBNs
JavaScript
15
star
59

plugin-versions

Display a <select> with other versions of your gitbook
JavaScript
15
star
60

markdown-css

Minimalist stylesheet (CSS or Less) for markup output
CSS
14
star
61

plugin-scripts

Include scripts in your GitBook
JavaScript
14
star
62

plugin-sharing

Sharing button in toolbar for GitBooks
JavaScript
14
star
63

tokenize-english

Javascript tokenizer for english sentences
JavaScript
14
star
64

diskache

Lightweight Golang disk cache
Go
13
star
65

mimedb

An extensive mime database in Go
Go
13
star
66

DraftMirror

Draft.js-like API on top of ProseMirror
JavaScript
13
star
67

normall

Normall: normalize filenames, accents etc ... in JS
JavaScript
13
star
68

plugin-highlight

Default syntax highlighter for GitBook
CSS
12
star
69

unstated

Simple state management for react
TypeScript
12
star
70

services-slack

Slack notifications service
JavaScript
12
star
71

plugin-gist

Embed Gist in your book
JavaScript
10
star
72

monorepo

A big home for small repos
Go
10
star
73

slate-edit-footnote

A Slate plugin to handle footnotes
JavaScript
10
star
74

lru-diskcache

A disk cache object that deletes the least-recently-used items
JavaScript
10
star
75

slate-edit-blockquote

A Slate plugin to handle keyboard events in blockquotes
JavaScript
10
star
76

plugin-styles-sass

SASS custom stylesheets instead of CSS
JavaScript
9
star
77

node-epubcheck

Node wrapper for epubcheck
JavaScript
9
star
78

plugin-lunr

Backend for the search plugin using Lunr
JavaScript
9
star
79

geo-utils

Utilities to get countries, languages and US states
JavaScript
9
star
80

slate-trailing-block

Slate plugin to ensure a trailing block
JavaScript
9
star
81

eslint-config-gitbook

GitBook's ESLint config, following our styleguide
JavaScript
9
star
82

go-sqlpool

A high level pool for maintaining pools of *sql.DB databases (e.g: thousands of SQLite files)
Go
9
star
83

syncgroup

Like golang's sync package but allows locking per groups of (string) keys (e.g: syncgroup.MutexGroup)
Go
9
star
84

public-docs

9
star
85

plugin-infinitescroll

Infinite scrolling in your gitbook
JavaScript
8
star
86

node-tasqueue

Node.js job/task-queue library using disque
JavaScript
8
star
87

plugin-livereload

Live reloading for your gitbook
JavaScript
8
star
88

plugin-tonic

Embed Tonic notebook into your GitBook
JavaScript
8
star
89

markdown-tools

A small CLI interface to kramed with lots of useful markdown tools (like go's "go fmt", lexing, rendering ...)
JavaScript
8
star
90

openapi-autodoc

Generate a GitBook Space from an OpenAPI spec
JavaScript
8
star
91

slate-no-empty

Slate plugin to prevent the document from being empty
JavaScript
8
star
92

plugin-mixpanel

Mixpanel tracking for your gitbook
JavaScript
7
star
93

brightml

Smart utility rendering markdown-ready HTML
JavaScript
7
star
94

html2hs

Convert HTML to hyperscript for virtual-dom
JavaScript
7
star
95

kramed-text-renderer

Renderer for kramed outputting plain text that can easily be fed to a search indexer/tokenizer/...
JavaScript
7
star
96

plugin-sitemap

Generate a sitemap for the gitbook website
JavaScript
7
star
97

firebase-apparatus

Lightweight implementation of firebase-tools as a Node module
TypeScript
7
star
98

licenses-utils

Utilities to detect licenses from project
JavaScript
7
star
99

example-visitor-authentication

Minimalist NodeJS application for "Visitor Authentication"
JavaScript
7
star
100

plugin-superscript

Use superscript in your content
JavaScript
6
star