B Bookdown for your project

These lecture notes use a wonderful little R tool called bookdown. You have learned in this course how to use RMarkdown, writing self-contained notebooks. The lecture notes are made up of many notebooks, one per Chapter exactly. You can always submit one or several independent notebooks as part of your project submission, but consider using bookdown for the following cases:

  • You have interactive visualisations that you cannot render in Github alone (for instance, the tmap “view” plots).
  • You want your project to have a presence online, a link you can share with future employers or to add to your portfolio (the link will look like 02522-cua.github.io/your-name, for instance 02522-cua.github.io/barnabe-monnot).
  • You want to separate your project among several notebooks but have them read like a book, in sequence. For instance, you could have
    1. A landing page with an abstract/executive summary, a really cool visualisation…
    2. A first chapter on your research question, hypothesis…
    3. A second chapter on your exploratory data analysis.
    4. A third chapter with your analysis.
    5. A fourth chapter with a conclusion, future work, references.

Building a book in RStudio is really easy! I have done one for my own repository and all you have to do is copy the way I do it. You can follow these steps to try it out yourself:

  1. bookdown resources must live at the root of your project folder. Copy the following files from my repository to the root of your “RStudio project” folder, the one that is named after your name (e.g., barnabe-monnot), not your “CUA final project” folder:

    • _bookdown.yml (replace book_filename with your name or another title you like)
    • _output.yml
    • 01-chap1.Rmd
    • book.bib
    • index.Rmd
    • packages.bib
    • style.css
  2. Open index.Rmd and knit it. You will see a new folder appeared in your project, /docs. It is a special folder to tell Github that the webpages that were just knitted are the ones we want to host at 02522-cua.github.io/your-name. Doesn’t matter how it works: the point is, make sure to push the /docs folder!

  3. Close your project, and reopen it. Magic! A new tab appeared next to the Git tab you use to commit and push your work. That new tab is called Build. Everytime you want to update your project book, hit the Build Book button.

  4. Finally, let me know once you push your /docs folder for the first time. On my end, I need to toggle one small setting in your repos for your book link 02522-cua.github.io/your-name to become active.

4 easy steps to have a really professional-looking book! Way to differentiate yourself from the pack ;) If you have more questions, you can write to me or use this handy guide which has a lot more details about bookdown.