Brain Dump / FAQ

Congrats you got through most of CBW’s Bookdown Documentation!

Danger Zones

Here are some common mistakes that can lead to problems - danger zones!

  1. Forgetting to pull your workshop teams recent edits before you edit!

    Ex. Forgot to pull before editing?

    • Your git window will say (at the top of the window) your branch is ahead of the main branch
    • You will probably have to deal with a merge conflict
    • [this is pretty in-depth]

Potential Errors & Bugs

Trying to build and getting “Exited with status 1.”? Bad news: Your book is not building properly. Good news: here are some (hopefully) helpful debugging tricks.

  • “Error: LaTeX failed to compile _main.tex.” - Essentially, something in your code is not allowing the output to be produced properly. Something in your code is producing incorrect output that is not allowing output to be produced. > TIP: Try to comment out recent changes. Try to decipher what exactly caused the build to fail. This will help you find your bug.

  • [X].html not found - This may result in bad syntax that creates a faulty file. First, fix whatever bug caused that faulty file to occur. Then, rebuild. If you continue to get this error, it may be because the rebuild did not delete the previous faulty html file. Try deleting the docs file and rebuilding. (This can be a good debug solution in general!)

WARNING!

If you delete the docs folder, make sure to create an empty file, named ".nojekyll" and put it inside the /docs folder. R-generated figures will not appear without this.


  • If you get a bug where your website builds into a website that looks like it is made using very simple html, you may have to change your permissions. If you see “Permission denied” in your warning messages, trying running this command chmod -R u+w docs in terminal, in the folder containing your docs folder [CLARIFY ?]

  • “Could not produce X output” - by default, bookdown builds all possible formats: gitbook, pdf, epub versions. We only need the gitbook, so if you’re having issues, change your build settings to only creating the gitbook [CLARIFY + INCLUDE IMAGES]

  • A very common bug is “missing X package”, just install it using this command in your console (the bottom left window in RStudio) install.packages("missing package name, include these surrouding quotations")

  • Not being able to produce a specific format - If you’re getting one of the following errors:

    • bookdown::render_book() failed to render the output format ‘bookdown::pdf_book’
    • bookdown::render_book() failed to render the output format ‘bookdown::epub_book’

    There is an easy fix! Press the dropdown options in the “Build Book” button and select “bookdown::gitbook”. We only need to produce the gitbook (the html pages!) so it’s ok if we can not produce the other pages. (However, it is ideal if we could produce all format types, since not being able to may lead to more errors.) This was likely due to creating something in one of the other formats that does not work in that format.

    For example: “File ‘…_svg-tex.pdf’ is missing.” is a bug that only occurs when producing bookdown::pdf_book. It occurs since you are calling a svg image in regular markdown, which is not allowed. If you want to display a .svg image, use HTML code.

  • Lines ?-? in _main.Rmd caused 50+ errors. This is most likely because of a bug in your code. Fixing this bug and rebuilding should fix this.

    A very weird bug…

    In the process of debugging, did you try editing/deleting lines of code you knew were related to bug? When you tried to rebuild your website, did those lines of code regenerate?

    This is a very weird bug, and it is hard to say what causes it (for me, it was because I accidentally deleted a comma). My best piece of advice is to copy all the changes you made, that didn’t cause a bug. Then, test it on a different device (perhaps one of your workshop team members, so we know bookdown has been working properly). Rebuild the website. (If you can not test on another device, make sure you copy your valid changes somewhere you can access it. You can try manually editing files on GitHub, to include code you know won’t fail.) Then, delete the project from your local computer, and reclone the repository from your GitHub. Make sure to git pull the updates!

Ease of Use

Wrapping Your Code

Sometimes, RStudio defaults so that there is no text wrapping when viewing your files. If you notice that you have to scroll horizontally to see the long lines in your files, turn on “Soft-Wrap Long Lines”.

  1. In your upper left corner of your RStudio Window, you will see options “File”, “Edit”, “Code”. (If you are in full-screen on a mac, you will have to bring your cursor to the upper left corner before seeing these options). Click “Code”.

  2. Go to the 5th option “Soft-Wrap Long Lines” and select it.

Visual R Markdown

If you are having difficulties using Markdown Syntax, RStudio has a work around! See Visaul R Markdown for more information.

FAQs

  1. I made a change via GitHub and and it’s not appearing on the website. Why can I not see my edit?

    Let’s recall this image.

    We build our HTML files using Bookdown. This means, any edits we make have to be local, so we can build our website and have the changes in our HTML files. GitHub Pages (which generates our website) only looks at the HTML pages, so even though there is a change on GitHub, it is on the .Rmd files. Hence, we don’t see it on the actual website!

    Next Step: Git Pull your change locally. Build the website. Git Push and then see your edits once the website finishes deploying!