Lessons from GitBook: My First Comedy of Trials and Errors

With most software development projects, you will need to set up your development environment by running a series of installations. GitBook is no different. Sometimes, your new installation just works, but often, you will have to do some manual configuration, and yes, GitBook required a few manual activities.

The work that I usually have to do involve researching package.json errors that happen when you do not run the npm init command. The videos on Treehouse set me up to know that step even when tutorials leave it out. You can see the practice set-up here, followed by the first problem, which was actually a README error:

An image:

In case you missed it:

FileNotFoundError: No "README" file (or is ignored)

I searched the error on the Web and found this Github issue describing previous users' request to basically generate the error I was getting. GitBook defaults to the README.md as the first page of your blog, so users wanted a feature that would let them ignore the README file and allow them to default to a first page with whatever name they wanted. You may follow the string here) if you want to folllow the conversation.

Somehow, I found my way to this:

I laughed (because I do not read Italian) and then read the post that had linked me to the Italian page. There was a conversation (in my native language!) in which users were requesting that the npm init not default to a README. Incorporating that feedback probably led to the problem of my README being ignored.

I tried changing “main” to README in the package.json file and ran “gitbook build.”

It failed.

I explored this advice:

I didn't actually want to ignore the README, and it turned out that I just needed to change the name of the file to “README.md.” Little things! But I was on a path to working out the bugs in my flow with NPM modules, so it was a welcome part of the journey.

Git and Hub

It was easier to clone and adapt a sample from Github than to build a whole new Gitbook from scratch. I started with this template: https://github.com/GitbookIO/theme-default. Then it occurred to me that to get the most out of the GitBook portion of this exercise, I should try to clone (or use some similar process) using Gitbook. I was trying to figure out how to get into a more native Gitbook workflow rather than bringing in data from Github, so I installed Hub, a wrapper designed to simplify Git commands and experimented with Hub for the Github tutorial.

Hub suggests that you create an alias using the command below so it feels more like the Git you are used to using. To us, it made sense to make it clear for ourselves when we were using Git vs Hub commands.

a02100@hello-computer ~/Desktop/github-practice-for-gitbook (master) $ gitbook alias ./github-practice-

I tested out several Hub commands in the tutorial for Gitbook, and they worked, except for the “gitbook fetch beta” command. That was fine because I do not have a beta version of a repository yet.

These show a difference between git and hub commands:

There is a Hub cheat sheet here). You can also type “man hub” (without the quotes) into the command line. The following Hub commands will give you the basics.

There were too many conflicts using Git and Hub commands. There is a learning curve to understanding which Git and Hub commands were the same and where they should point. This page helped clarify pointer information and would be useful if we were going to incorporate Gitbook into out workflow, but since the experiments we ran met the specs, we decided to focus on a different workflow. Here is what “hub config -l” generated from the command-line from advice on https://www.drupal.org/node/1286026 :

I edited the README file and tested Hub commands for my Gitbook branch. The first time I accidentally typed “git” and it worked. The second time, I ran the commands using “hub,” which also worked:

I had successfully pushed to my branch on Gitbook:

A Note on Blogs and Databases

Although GitBook has some improvements to make before becoming a good tool for collaborating with another person, it still works as a blog hosting solution. If you are using GitBook, you can put your blog on the Web without using Heroku or manually setting up hosting. However if you are hosting your own blog, you might consider using Javascript and/or Python to store your blog contents in a SQL database.

For this project, we initially considered PostgreSQL as the database to use. So far, most of the tutorials I reviewed recommended Python frameworks such as Django and Flask, just as Javascript tutorials recommended Express, for example.