Chapter 28 Caring for your book

In this chapter, we’ll cover things you should keep in mind as you create content and start to use your book.

28.1 Workflow for maintenance

Now you know how to order your .Rmds, so what does the workflow look like to add more .Rmds as you update your book? Here’s what it’s like for us:

Open my existing site RStudio project
Go to Addins > Preview Book to render the book
Create a new .Rmd document in RStudio using File > New File > R Markdown, and delete its default YAML entirely.
Begin with a fresh # Level 1 header and then go about creating new content.
Update _bookdown.yml to include the new page.
Go to Addins > Preview Book to render the book again
Rinse and repeat if needed!
Commit and push all changes to GitHub.

28.2 Rendering

In 26.7, we mentioned that there were several options for rendering your book locally. Here are the others, and some notes about when/ why you would choose one over the other:

Addins > Preview Book: renders only the gitbook version of the book.
The line below does the exact same thing as Preview Book:

bookdown::render_book('index.Rmd')

Or you can use:

bookdown::serve_book()

Using the Build Book tab in the IDE: this renders all specified book formats, unless you specifically choose something different from the Build Book dropdown menu.

preview_chapter("my-chapter.Rmd"): Is rendering the entire book taking way too long? Run preview_chapter() instead to render just a single chapter. One caveat is that any cross-references to other chapters won’t work, since only the chapter being previewed is updated.
Remember, never Knit!

When rendering your book with a previous preview window open, you might experience a never-ending loop of book-rendering. This is a common problem! Exit out of this by going to Session > Terminate R….

28.3 Using your book

28.3.1 Components

As you build content for your book, don’t forget about the bells and whistles you can use in bookdown, like the ones below. For guidance on how to use these, check out the bookdown documentation:

28.3.2 Search

The built in search feature in your book can be useful for both you and your learners–but the way it works is a little tricky! You can see the instructions for it by clicking on the in the toolbar.

As you enter your search term into the box, the TOC is filtered to show only the sections were your search term appears.
Don’t move that cursor– keeping it hovered over the box, you can use your arrow UP and DOWN keys to navigate from the term’s first occurence to the next through the book.

28.4 Hiding Chapters

Books can take a while to write– and that’s okay. Don’t be afraid to put your book on GitHub pages or another platform before you think it’s completely finished. Sharing your bookdown site publicly, even as the content and chapters evolve, can be an important part of the making-process (and is also really great for soliciting community feedback).

It’s not possible to keep your files completely concealed once you’ve pushed them to a public repo on GitHub, but there are some ways you can make works-in-progress difficult enough to discover that it’s unlikely anyone will stumble across them. If you do want to keep all or some of your book under wraps, then you have a couple of options:

Easy: Upload your source to GitHub, but don’t share the GitHub pages link in the GitHub repo description. Savvy GitHubbers can still guess your URL if you have turned on GitHub pages, or they’d be able to clone the repo and build it locally, but it would take some grit!).
Medium: Hide individual chapters by not adding their .Rmd file to the _bookdown.yml. OR, if you’ve been following our configuration settings and have used new_session: yes, then placing your .Rmd in a sub-folder within your project will also keep it hidden.
Advanced: A more advanced workflow would involve creating a GitHub branch for works in progress and waiting to merge those into the master branch until they’re ready for showtime.

28.5 Staying organized

You may find that as your book content grows, your project directory (and possibly your mind) will start swimming in .Rmds and other files. Unfortunately, there’s no good way to keep your .Rmds organized with subdirectories if you’re following our suggestion to use new_session: yes. But, you can do a little bit of clean up by creating folder for your images (images/) and another one like assets/ to place HTML and CSS files. But if the Marie Kondo within you is still not satisfied, then you might consider creating a Blogdown site.