search

scottsteinbeck / commandbox-gitbook

A CommandBox module for converting a Gitbook into an eBook
25 stars 3 forks source link

readme

CommandBox GitBook Exporter

A CommandBox module for converting a GitBook into a PDF/eBook. This is an open source community module and not endorsed or affiliated with GitBook. You are welcome to contribte to this project via pull request. The code is written in CFML, a modern JVM scripting language which totally r0x0rs.

Installation

Use of this module requires CommandBox, a CLI tool for all operating systems. CommandBox can be installed via HomeBrew, deb/yum repos, or direct download.

https://commandbox.ortusbooks.com/setup/installation

Once you have box, install this module with the following command:

box install gitbook-exporter

To check for updates, run the following command

box update --system

CommandBox Basics

CommandBox (or box as the binary is named) commands can be run as follows:

box gitbook toc

or for a better experience, you can enter the CommandBox shell (similar to Bash) 

box

and then run your command without the box portion since you're already "inside" of box. 

CommandBox> gitbook toc

This provides a faster experience and also allows you to use the built in tab-completion that the box shell provides for all commands, params, and values.

More information here: https://commandbox.ortusbooks.com/usage/execution

CommandBox allows named or positional parameters, so the following are equivalent.

CommandBox> gitbook toc /path/to/export current
CommandBox gitbook toc sourcePath=/path/to/export version=current

GitBook commands

The gitbook namespace has three commands.

Acquire your book export

In order to use the command, you will need to export the contents of your book from the Gitbook.com website. Under Advanced, expand Danger Zone and click the red Export button. Make sure you don't hit Delete instead! You will download a zip fie containing JSON files and images that describe all of the content in your book.

You can point to the zip when you run a command 

CommandBox> gitbook toc /path/to/export.zip

Or you can unzip the archive and point to the folder which will prevent the temp fies from being deleted every time you run an export:

CommandBox> gitbook toc /path/to/exportFolder

The recommended and easiest approach is simply to unzip the archive, cd into the root of the unzipped book export and run the commands from there. They will "find" the book via convention.

CommandBox> cd /path/to/exportFolder/
CommandBox gitbook toc

List Book Versions

List the versions of a book export and the book title with the gitbook versions command.

CommandBox> gitbook versions

My Book Title

 - 1.0.0 (master)
 - 1.0.2

In the example above, 1.0.0 is the title of the version, but master is the branch or folder name used to store it.

List Book Table Of Contents

List the TOC from a given version of a book export and the book title with the gitbook toc command. By default, the default verson of the book will be used.

CommandBox> gitbook toc

My Book Title (1.0.2)

  Section 1

  Section 2
    ├── Sub Page A
    └── Sub Page B

  Section 3
    ├─┬ Sub Page C
    | └── Sub Sub Page D
    └── Sub Page E

To view the TOC for a specif version of the book, pass in the title of the version you wish to see.

CommandBox> gitbook toc version=1.0.0

Export Book Contents

The gitbook export command is likely what you're here for. It will parse the JSON export files, download any missing assets, render HTML partials for each page, and then export that to PDF or other formats (coming soon).

CommandBox> gitbook export

You can specify the book export and version you want to export:

CommandBox> gitbook export sourcePath=/path/to/ExportFolder version=1.5.6

Export formats

By default, all formats will be created (HTML, PDF). You can export only formats you want (whitelist):

CommandBox> gitbook export --PDF
CommandBox> gitbook export --HTML

or turn off formats you don't want

CommandBox> gitbook export --noPDF
CommandBox> gitbook export --noHTML

Note, --PDF is the same as PDF=true and --noPDF is the same as PDF=false.

General Export Settings

You can control several general export settings by passing additional params to the command. To see all the options run gitbook export help.

Example: 

CommandBox> gitbook export coverPageImageFile=myBookCover.jpg codeHighlighlightTheme=fruity --noShowTOC --noShowPageNumbers --noShowTitleInPage

Hint, when using the interactive CommandBox shell, you can use tab completion to get suggestions on possible Pygments themes and file system completion.

PDF Page Export Settings

There are a handful of export settings that are passed to the underlying PDF engine to help control the page size. To see all the options run gitbook export help.

Example: 

CommandBox> gitbook export pageType=letter orientation=landscape
CommandBox> gitbook export pageType=custom pageHeight=9.5 pageWidth=6.25 unit=in margintop=.5 marginbottom=.5 marginleft=1 marginright=1

Authors

Development of this module was sponsored in part by Ortus Solutions. https://ortussolutions.com/

Support

This is an open source and free module. The source code is located here, and written in CFML:

https://github.com/scottsteinbeck/commandbox-gitbook

Please enter tickets for any issues you have:

https://github.com/scottsteinbeck/commandbox-gitbook/issues

If you just want to ask a question, you can reach the authors as @bdw429s and @Scott Steinbeck on this public Slack team: https://boxteam.herokuapp.com/