I’ve long had a desire to share whatever information I have with anyone who wants to know, so a blog and a book are both ideal media for me. Over the past ten years or so I wrote the textbook and lab manual for a digital logic class I teach at Cochise College plus a lab manual for the Business Research Methods class I teach at the University of Arizona South. I constantly update all of those volumes and am also working on the textbook for the Business Research Methods class. Finally, I have a desire to share any lessons I learn in my regular research at Cochise College.
I suppose like most writers, I started with Microsoft Word. I was not too satisfied with my experience with Word so I shifted to Open Office, where I could make use of master documents. However, that did not work out very well. Then I discovered \(\LaTeX\) and things would not be the same again. I installed TexStudio and began to write with all of the tools that \(\LaTeX\) makes available. I learned how to create graphic images with TikZ and created dozens of digital logic diagrams. I created well-formatted documents for all of my classes and then rested, confident that my students were getting good information at the right price (free!).
I attended the rstudio::conf in 2018 and attended a two-day class about GitHub and suddenly my problem of version control and synchronizing documents between home and office was solved. I am far from a GitHub guru but I can at least create a repository and keep my computers synced.
At that same conference I saw a presentation of blogdown. That was so inspiring that while I was there I purchased the Blogdown, Bookdown, and Dynamic Documents books written by Yihui Xie. That evening, I installed blogdown on my laptop and was able to create a new blogdown site on an unused domain I owned – all within about an hour. I then began to explore the possibility of replacing \(\LaTeX\) with bookdown for the books I had written and soon converted my Business Research Methods lab manual, which teaches students how to use R for analysis, to bookdown. One of the most important improvements bookdown brought to my class was the ability to embed Datacamp Light code blocks in my book. Using an online bookdown site I do not need to worry about students installing R on their home computers or complaining that the college’s computer lab did not have R installed. I was able to set up the lab and control the environment so my students could complete their work without computer issues.
This document records my experience with both blogdown and bookdown. Other instructors who may be travelling down a path similar to mine are free to contact me — I’m willing to help all that I can.
In general, the instructions given in the blogdown book are fairly easy to follow and will quickly create a blogdown site. The default theme was not very appealing to me so I opted to download the “Academic” theme and get that set up. Again, there is a good bit of help available at the Academic Theme Homepage. Because I wanted to have the experience of simply uploading changed content to Github and let that automatically deploy the post, I also opted to create a free account at Netlify then linked that account to my Github account. Finally, I had a domain name that I have used on-and-off over the years so I decided to use that domain for my blog, so I had to set the Domain Name Servers to point to the Netlify site.
I later decided to stop using the Academic theme and begin with Ghostwriter. I chose Ghostwriter because it is much simpler and easier to maintain and, honestly, simple is normally better for me. There were just a couple of “got-chas” along the way.
It took me forever to find the names of the Netlify domain name servers. After I found those names I recorded them in a file I keep on my personal computer just in case I need to use them again.
The Netlify user interface was a bit confusing for me. For example, at one time I wanted to force a “deploy”" cycle and I looked around the site for a long time to find that button. (To complete the record, I now know exactly how to find that button and can force a re-deploy in a matter of seconds.)
Early on, my deployment builds failed with an error message I did not understand. I Googled the message and found out that the most common reason for that error was a mismatch in the version of Hugo used inRStudio and that used on Netlify. It took some time for me to find the Hugo version number on my home computer, but to be honest, there is a function named, oddly enough,
blogdown::hugo_version()and after searching online and in R for some time I finally stumbled on that function. Then, I had to change the deployment version on Netlify to that number and it took far too long for me to find the right place to enter the Hugo version number.
It started taking a long time for me to “build” my site and I tried to find shortcuts, but that effort failed in an odd, and spectacular, way. I tried using the
blogdown::build_dir()to just build the one directory that I had changed, but my files would not be rendered as regular HTML but, rather, as a self-contained script. That meant that little things like the “date created” was incorrect. I learned that I had to rebuild the site on my local computer with
blogdown::build_site()and then push the site to GitHub.
From the outset, I’ll say that I like Bookdown. Like Blogdown, I was able to read the instructions in the Bookdown book and get that package installed in RStudio with a “demo” book in a matter of a few minutes. The setup for the book is simple and is little more than tweaking text settings in the config.toml and index.Rmd files. My book includes a lot of R code along with DataCamp-Light blocks so students can explore R without installing that on their personal computers. I’m not able to save the book in a useful .PDF format since the DataCamp blocks cannot be rendered in PDF, but that is fine with me since the book is only useful online anyway.
I started the textbook for that same class and after a couple of chapters I built a PDF book without any trouble. I was also plesantly surprised at how well the bibliography feature works with bookdown. For the HTML version appropriate bibliographic entries are printed at the end of each chapter (each chapter is in a separate file) and in a new chapter named “References” at the end of the document. The PDF version prints the references as footnotes and, again, at the end of the document. This is a really nice way to handle a bibliography.
When I click the “build” button, an entire website is created in a directory named “_book“. Then, all I have to do is use an FTP client to copy that entire directory to my web host and the book is ready to be used. There couldn’t be anything much simpler to do, especially given that most books do not change very frequently.
My bookdown book can be found at georgeself.com and the work I do with blogdown can be found, of course, in the blog that you are currently reading.
I like both of these writing systems and envision using them for a long time to come. They are simple to use and give a writer an opportunity to publish online with very little overhead.