Keeping book source in GitHub

This section needs rewrite - do not use it while this warning is here

GitBook books living in GitHub

This document is a part of Aurelia-Tools internal documentation library. It describes the process of its own creation using only the browser to do it.

If you already have a book in GitBook repository and want to transfer it to GitHub, start reading at section 2. below.

1. Create a new book

Point your browser to our GitBook main page: https://www.gitbook.com/@aurelia-ui-toolkits and click on the + NEW button (Image 1, below)

Image 1

This should result with the Create a new book dialog: (Image 2 below). Define your choices in the order suggested by red markers.

Image 2

I also deleted the "Chapter 1" page that is a part of the template selected with the click on item tagged with red marker 1 on the Image 2 above. For this document, a single page is sufficient.

Now, our book is created and can be accessed via URL https://aurelia-ui-toolkits.gitbooks.io/gitbooks-living-in-github/details and as the URL suggests, it is persisted on the gitbooks.io server - not in GitHub.

2. Transfer the book to GitHub

Summary of actions

The summary of actions described How can I transfer my content to GitHub? - section Using the command line is:

• create the new repository in GitHub that should have the same or similar name to your current repository on GitBook, created as the consequence of the action in step 1. Create a new book above.

• get the git url of your GitBook book repository which is typically defined as https://git.gitbook.com/MyName/MyBook.git

• -clone this book to your machine

• push this local clone to the newly created GitHub based repository (with the intent to ovewrite that destination.

2.1 Open the book

Point your browser to https://aurelia-ui-toolkits.gitbooks.io/gitbooks-living-in-github/details and click on the SETTINGS link (Image 3 below)

Image 3

2.2 Create the empty repository on Github (new home for your book)

This is the critical step that is not well explained in the existing documentation.

Image 4

Click on Create repository buttom (marker 5, Image 4) results with the new GitHub repo with the URL https://github.com/aurelia-ui-toolkits/GitBook-books-living-in-GitHub

2.3 Clone the original book to the local computer

This is simply done as:

C:\work\tests
λ git clone https://git.gitbook.com/aurelia-ui-toolkits/gitbooks-living-in-github.git
Cloning into 'gitbooks-living-in-github'...
remote: Counting objects: 47, done.
remote: Compressing objects: 100% (45/45), done.
remote: Total 47 (delta 12), reused 5 (delta 0)
Unpacking objects: 100% (47/47), done.
Checking connectivity... done.

2.4 Push this local book clone to GitHub

Again, using your console, you need to do your equivalent of this

λ cd gitbooks-living-in-github

C:\work\tests\gitbooks-living-in-github (master)
λ git push https://github.com/aurelia-ui-toolkits/GitBook-books-living-in-GitHub master --force
Counting objects: 47, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (45/45), done.
Writing objects: 100% (47/47), 6.32 KiB | 0 bytes/s, done.
Total 47 (delta 12), reused 0 (delta 0)
remote: Resolving deltas: 100% (12/12), done.
To https://github.com/aurelia-ui-toolkits/GitBook-books-living-in-GitHub
 + 818e464...af55099 master -> master (forced update)

C:\work\tests\gitbooks-living-in-github (master)

3. Set GitBook editor to manage your new copy in GitHub

Point the browser to https://github.com/aurelia-ui-toolkits/GitBook-books-living-in-GitHub and observe:

Image 5

In order to associate the GitBook web editor with your book stored in GitHub, click on the Settings link (Image 5, marker 1). This will result with

Image 6

Click on the Browse directory icon (Image 6, marker 1) will bring the list of all GitHub integrations. Scroll down until you see the GitBook icon

Image 7

Click on the GitBook icon establishes the needed relationship, where your book is stored in GitHub, can be edited by GitBook web editor and will be hosted (as a web site) at GitBook.

Image 8