CBW Bookdown Guide
I Introduction
1
CBW’s Bookdown Documentation
2
How Bookdown Works: A Primer
II Cheat Sheets
3
Editing Your Workshop
4
Resolving Merge Conflicts
5
Handy Shortcuts
5.1
Getting to your folder in the terminal
5.2
Opening your folder from the terminal
5.3
Commenting and uncommenting in RStudio
6
FAQs
6.1
Why aren’t my changes appearing on the website?
6.2
What are the unusual symbols I’m seeing?
6.3
Why aren’t my links to external sites working?
6.4
Why aren’t my
git pull
commands working?
III Setup and Installations
7
Installations
8
Local Setup and SSH
8.1
SSH Connection
8.1.1
Generate an SSH key
8.1.2
Add your SSH key to the ssh-agent
8.1.3
Add your SSH key to your GitHub account
8.2
GitHub Folder
8.2.1
Create your folder
8.2.2
Clone the GitHub homepage
8.2.3
Clone the travel logistics repo
8.3
Set merge preferences
IV Set Up Workshop Site
9
Create your repo
9.1
Option 1: New repo
9.2
Option 2: Duplicate existing repo
10
Configure your repo
10.1
A note on repos vs websites
11
Deploy your site
11.1
Check your deploy and see your website!
A very specific build and deployment warning
12
Faculty team setup
13
Clone to your computer
13.1
Oops, I Git Cloned the Wrong Repository!
14
Finishing touches
15
Link to homepage
15.1
Get your code
15.2
Add to GitHub homepage
15.3
Add to GitHub sitemap
15.4
Update the website
16
Logistics page
16.1
Create your logistics page
17
What’s next?
17.1
Homepage
17.1.1
Pre-work
17.1.2
Schedule
17.1.3
Class photo
17.2
Faculty pages
17.3
Computing
17.4
Modules
17.4.1
Embedding slides
17.4.2
Embedding YouTube videos
17.4.3
Adding lab material
17.5
Bioschemas
17.6
What if I need to add a new file or change the existing file structure?
V Formatting
18
Markdown
18.1
Formatting your content
18.1.1
Option: Visual R Markdown
18.2
Chapters and subheaders
18.2.1
Sub-subheader
An unnumbered subheader
18.3
Parts
18.4
Text Formatting
Bold
Italics
Subscript
Superscript
Footnotes
Horizontal Line
Blockquote
Unordered List
Ordered List
Code
18.5
Links
External webpages
Other sections within your workshop website
18.6
Embedding
Images
PDFs
YouTube Videos
18.7
Citations
18.8
Equations
18.9
Theorems and Proofs
18.10
Using HTML
19
Callouts
19.1
Callout generator
19.2
About callouts
19.3
Callout options
19.4
Default icons
19.5
Style examples
19.5.1
Regular
19.5.2
Important
19.5.3
Subtle
19.5.4
Plain
19.6
Indenting callouts/nesting in lists
19.7
Advanced example
20
Code
20.1
Rendering Code
20.2
Syntax highlighting
20.3
Running code
20.4
Code Chunk Options
20.5
Code Chunks for Code-Generated Figures and Tables
VI Working with Git and GitHub
21
Merge conflicts
21.1
What is a Merge Conflict?
21.2
What does a merge conflict look like?
21.3
Fixing the conflict
21.3.1
Part 1: Fix Conflicts in
.Rmd
Files
21.3.2
Part 2: Fix Conflicts in the
docs/
Folder
22
Branches
22.1
What are branches?
22.2
Using branches
22.2.1
Create a new branch
22.2.2
Make your changes
22.2.3
Push your branch
22.3
Creating a Pull Request
22.4
Managing Pull Requests
VII Reference Material
23
Command line crash course
23.1
Terminal, Command Prompt and Windows PowerShell
23.2
Common Commands (for us)
24
Bookdown crash course
24.1
How Bookdown works
24.2
File setup
_output.yml & _bookdown.yml
Organizing the TOC: .Rmd files
Folders
24.3
Working with your Bookdown project in RStudio
24.3.1
Opening your Bookdown project
24.4
Explaining RStudio
24.5
Build the Book
24.5.1
Other Ways to Build Your Book
24.5.2
Knit Your Book
24.5.3
Knit VS Build
24.5.4
Preview Your Book
24.6
Pushing to GitHub
Appendices
A
Appendix A: developers’ guide
A.1
GitHub Repo
A.2
Diagram Links
A.2.1
How to Publish a Google Drawing
B
Appendix B: homepage guide
B.1
Project Structure
B.2
How to Update Content
B.2.1
Add Your Image
B.2.2
Edit workshops.json
B.2.3
Example Entry:
B.3
Local Development & Validation
B.3.1
Live Validation in VS Code (Recommended)
B.3.2
Manual Validation via Command Line
B.4
Deployment
B.5
Common Debugging Steps
B.5.1
Symptom: The page is blank or workshops are not displaying.
B.5.2
Symptom: My recent changes are not appearing on the live site.
B.5.3
Symptom: A workshop card is showing a broken image.
C
References
Sponsors
CBW Bookdown Guide
C
References
Xie, Yihui. 2025.
Bookdown: Authoring Books and Technical Documents with r Markdown
.
https://github.com/rstudio/bookdown
.