Publishing with GitBook

Pushing the Book to Git(Hub)

To use Git for versioning and collaboration, you need to initialize the book's directory as a Git repository and push it to GitHub or a repository on your server. To do this, switch to the my_book directory and run the git init command. Then, use the git remote add origin command to connect the local repository to the one on GitHub.

If you set up a Git repository on your own server, you should use the

git remote add origin ssh://user@remotehost/path/to/my_book_repo

command to add the remote host to the repository (replace user with the actual username, remotehost with the server's IP address or domain name, and path/to/my_book_repo with the path to the remote repository). To add all files, commit the changes, and push everything to GitHub or your own repository, run the following commands:

git add -A
git commit -m "Initial commit"
git push origin master

You need to run these commands every time you want to commit and push changes to the repository. However, you can automate this process by adding the following function to the ~/.bashrc file:

function gitc
git add -A
git commit -m "$HOSTNAME"
git push origin master

The next time you commit and push changes, open the terminal, switch to the my_book directory, and run the gitc command. The function uses the machine's hostname as the commit message, which offers a convenient way of identifying the source of the latest commit (which is handy if you work on the book from different machines).

Once you've pushed the book to the GitHub repository, other contributors can review changes, create forks, and submit pull requests. You can also use Git to track changes and revert to previous versions, among other things. Even if you don't need this functionality for working on the book, you can use Git as a replacement for third-party file syncing services to keep the book project in sync on different machines.

Publishing the Book

When the book is ready, you can publish it on GitBook. Before you do this, however, you need to add a cover and connect the editor to the GitBook service. To do the former, choose Book | Set Cover Picture and select an image you want to use as a cover. The image must be in the JPEG format, and its dimensions should be 1800x2360.

To link the editor to the GitBook service, choose Book | Advanced Settings (Figure 5), enter your username and token in the appropriate fields, and press OK. Then, choose Book | Publish As, select the existing book item from the Book drop-down list, and specify the version number in the Version field. Hit OK to push the book to GitBook.

Figure 5: Configuring advanced settings.

Once the book has been pushed to GitBook, the service builds an ebook in the supported formats. You can monitor the build process in the Activity section of the book page on GitBook (Figure 6).

Figure 6: You can monitor the status of the building process in the Activity section.

The GitBook editor also lets you generate local copies of the book in different formats for distribution through other services and channels. Using the available build commands under the Book menu, you can output the book in the PDF, EPUB, and MOBI formats as well as generate a static website (Figure 7).

Figure 7: Besides supporting the PDF, EPUB, and MOBI formats, GitBook editor can turn the book into a static website.

Alternative Markdown Editors

Because any GitBook-based book is just a set of Markdown-formatted, plain-text files, you can use any Markdown editor for working with the book. Of course, GitBook's own editor is still the best tool for the job, but in some situations, using it isn't an option. When you need to tweak a chapter on an Android device, you can use the excellent DroidEdit code editor [7] for editing and the SGit app [8] to pull and push changes. If you use GitHub for the book project, you might appreciate GitHub's own editor, which supports soft wrap and the Zen Mode for a distraction-free writing environment. Using the editor, you can edit the book right in your browser.

If GitHub's editor is not your cup of tea, you might want to give Prose [9] a try. This slick and lightweight Markdown text editor integrates nicely with GitHub. Once authorized, the editor gives you access to all your GitHub repositories. As a Markdown editor, Prose supports Markdown syntax highlighting, and the editor's interface features a toolbar that gives quick access to all basic formatting options (Figure 8).

Figure 8: The Prose editor lets you edit files in a GitHub repository.

Using the hosted version of Prose is the easiest way to start using the editor. However, the editor is released under an open source license, so you can grab the source code from the project's GitHub repository and deploy the software on your own server.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus

Direct Download

Read full article as PDF:

Price $2.95