Using Gitbook
This is my first book written in Gitbook. These are comments (sometimes to myself) about some points to be careful with.
Gitbook, the website, provides an online editor. It works quite well, and you don't have to figure out how to push changes onto the website -- they are there automatically. Just click the "Publish" button.
You do need to configure the Gitbook so that certain features will run. In my case, I needed to include something to allow math formulas to display (mathjax plugin) and something to allow Youtube videos to appear in the book (youtube plugin).
It wasn't clear to me at first how to get these plug ins. At the top of of the editor page, on the far right, is a small triangle in the menu bar. Click on it, and it provides a number of options. First is "Edit Book Configuration." If you know about .json files and such, you can click on that and edit directly the book.json file, which will allow you to manually insert a request to load in the plugins.
More likely, though, you just want to point and click to something that will do it for you. So go to the triangle, click and select the menu item "Plugins Store." Selecting this item will allow you to search for various plugins and install the ones you need. (In my case, I needed mathjax and youtube.) Try that, it should work.
Publishing -- when you click the "Publish" button, everything is update on the web for you. However, anyone viewing the published version online may not see the newest version immediately. This includes you yourself, if you are monitoring the progress online. I'm not sure why -- there are some latency issues in the updating, and caching issues with your browser, where the browser may use a local, old copy of the book rather than fetching the newest one.
I don't know an immediate fix for this.
Gitbook seems to prefer .png files for images. I haven't figured out how to post .pdf and .svg image files in Gitbook, even though these are more natural to create algorithmically. I've been cheating-- create a .svg file, display it on the Mac, grab an image and convert it to a .png file. There must be a better way.
Importing .png files to display is very unreliable. I am trying to use commands like this:
 or
but Gitbook seems to have a hard time finding the files that are there. If I try not to move them around, or rename them, it seems to work better. But then my files are disorganized.