You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 0010-cheatsheet.Rmd
+15-2Lines changed: 15 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -50,9 +50,10 @@ This section is a quick reference on setting up GitHub Pages site for workshops.
50
50
**8. [Finishing touches](#finishing-touches)**
51
51
52
52
* Open the .Rproj file in the folder you've just downloaded
53
-
* Upload your workshop icon to the ``img/`` folder
53
+
* Upload your workshop icon to the ``img/`` folder and sponsor logos to the ``img/sponsors/`` foldder
54
54
* In _output.yml, replace ``missingimg.png`` with your icon's filename
55
-
* Hit "Build Book" and check preview once complete
55
+
* In _output.yml, add sponsors
56
+
* Hit "Build Book" and check preview once complete. Note that you may need to adjust sizing of sponsor logos and build again
56
57
* Commit and push
57
58
58
59
**9. [Add content](#whats-next)**
@@ -116,3 +117,15 @@ If you are working in the Terminal and want to open your folder in your file exp
116
117
117
118
## Commenting and uncommenting in RStudio {#commenting}
118
119
To quickly comment or uncomment lines in RStudio, use `Command + Shift + C` (Mac) or `Ctrl + Shift + C` (Windows/Linux).
120
+
121
+
122
+
# FAQs {#faq}
123
+
124
+
## Why aren't my changes appearing on the website? {#changes-not-appearing}
125
+
There are a few things that could be the cause:
126
+
127
+
1. You forgot to *build your book*. Remember that this step is what creates the HTML files for the website.
128
+
129
+
2. You forgot to *commit and push your changes*. The build step creates the HTML files, but you need to push them to Github after building - otherwise, they only live on your computer.
130
+
131
+
3. You just haven't waited long enough - it takes 1-2 minutes for the site to build.
Copy file name to clipboardExpand all lines: 0020-installations.Rmd
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# (PART) Setup and Installations {-}
2
2
3
3
# Installations {#installs}
4
-
You'll only need to run these steps once. tets
4
+
You'll only need to run these steps once.
5
5
6
6
1.**Download and install R** <ahref="https://cran.rstudio.com/"target="_blank">here</a>, version 3.6.0 or higher. Follow the instructions for your operating system (Linux/macOS/Windows).
7
7
@@ -72,7 +72,7 @@ You'll only need to run these steps once. tets
You may have to approve some downloads. Say "yes" and enter your password when necessary. This tells bookdown you are okay with downloading and installing these packages in their default locations.
Copy file name to clipboardExpand all lines: 0030-createrepo.Rmd
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
# Create your repo {#create-repo}
4
4
5
-
## New repo
5
+
## Option 1: New repo
6
6
7
7
1. Go to the **[bookdown template](https://github.com/cbw-dev/bookdown-template)**.
8
8
@@ -21,7 +21,7 @@
21
21
22
22
4. Click `Create Repository`.
23
23
24
-
## Duplicate existing repo
24
+
## Option 2: Duplicate existing repo
25
25
26
26
If you are repeating a previously offered workshop and know you'll mostly need to make minor edits, you can create a copy of an existing repo (a process called `forking`) instead of creating it from scratch.
Copy file name to clipboardExpand all lines: 0032-deploy.Rmd
+1Lines changed: 1 addition & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -27,6 +27,7 @@
27
27
Great! Now we're waiting on the page to build and deploy, which should take less than a minute.
28
28
29
29
## Check your deploy and see your website! {#check-deploy}
30
+
30
31
31
32
To see updates, go to the **Actions** page (found along the top navigation bar. This will help you understand how the deploy is working, and if it succeeded or failed.
Copy file name to clipboardExpand all lines: 0035-finishingtouches.Rmd
+3-2Lines changed: 3 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@
10
10
11
11
:::
12
12
13
-
4. In the same _output.yml file, add any sponsors not already included. To do this, copy one of the existing sponsor lines and change each section. Use the `height` or `width` attributes to change how large the images are. If two images are small enough and there is no `<br>` tag in between, they will be displayed side by side like the Genome Canada and Ontario Genomics logos.
13
+
4. In the same _output.yml file, add any sponsors not already included. To do this, copy one of the existing sponsor lines and change each section. Use the `height` or `width` attributes to change how large the images are. If two images are small enough and there is no `<br>` tag in between, they will be displayed side by side like the Genome Canada and Ontario Genomics logos.
@@ -18,91 +20,6 @@ The Build step is *required* for changes to be reflected on the website. If you
18
20
19
21
::::
20
22
21
-
# Opening your bookdown project in RStudio
22
-
23
-
Enter the folder you git cloned using Finder/File Explorer. It should be titled "[workshop-name]". Right click on the .Rproj file and press "Open in RStudio". There is only one file with this file extension.
**This file is what you will open each time you want to work on this workshop.** You must explicitly **open the .Rproj** file to build properly!
28
-
29
-
:::
30
-
31
-
A RStudio window should open up and look something like the image below.
32
-
\
33
-
34
-
## Explaining RStudio
35
-
36
-
In the bottom right, we have all of our files and subfolders. These files will be explained [below](#file-setup). This window also contains helpful views, like "Viewer" and "Plots". We will touch on these later.
37
-
38
-
Try opening `index.Rmd`: a new pane will open in the top left that shows the contents of `index.Rmd`. This is where we will be editing our files! Notice the "Knit" button.
39
-
40
-
In the bottom left, we have our console and other debug related windows (such as terminal!). Any code we run will appear in the console. We can access the terminal (just like editing in the Terminal app) under the "Terminal" tab.
41
-
42
-
In your top right, we have a different window with more different views. The most relevant windows to us are the "Build" and the "Git" windows.
Try closing (and maybe even restarting RStudio) and then reopening it. A "Git" tab should appear to the right of the "Build" tab and to the left of the "Tutorial" tab.
47
-
48
-
:::
49
-
50
-
## Build the Book
51
-
52
-
Try pressing "Build Book" within the "Build" window. Your build window is going to fill up with text, and soon, a website is going to pop up in a new window.
If it's your first time building, you may have to approve some downloads and installations, like we did in [the Install section](#installs).
57
-
58
-
:::
59
-
60
-
By building the book, **all** of these files are compiled and converted to .html files that create a website. Each time we make local changes to our files and we want them to appear in our website, we need to rebuild the book. Note that each time we build our book, the files we edited will be saved first - we don't have to save before building.
By default, RStudio will choose to build "All Formats":
66
-
\
67
-
You can choose to only produce a gitbook (the first option). This can be helpful if you are encountering errors claiming that "bookdown::render_book() failed to render the output format 'bookdown::pdf_book'/bookdown::epub_book'". Additionally, not producing all output formats can decrease your build time significantly.
68
-
69
-
:::
70
-
71
-
### Other Ways to Build Your Book
72
-
73
-
1. Build the book from the R console:
74
-
75
-
```{r, eval=FALSE}
76
-
bookdown::render_book()
77
-
```
78
-
79
-
2. Press the keyboard buttons: `cmd + shift + B` (macOS) OR `ctrl + shift + B` (windows)
80
-
81
-
### Knit Your Book
82
-
Building can take a long time. If you are editing just one file, you can press the "Knit" button that is at the top of the window with your file. This will run the code in the page, and show you what that page would look like in the website (as well as saving that file).
83
-
84
-
> Note: Other pages in your website will not update.
85
-
86
-
> A quicker way to knit is using the keboard controls
Building creates the website using **ALL** the .Rmd (and other) files. This is why it takes so long. Knitting creates/updates **only** the .Rmd file you're currently working in and reruns your code. (Note: You can't knit a non-.Rmd file!)
93
-
94
-
Before pushing to GitHub, it is a good idea to build, in case of faulty links or small bugs that occur if you only knit or preview.
95
-
96
-
### Preview Your Book
97
-
98
-
If you want live updates to your changes, you can preview the page as you edit the book when you save individual .Rmd files. You can start the server in a work session by using the RStudio add-in "Preview book", or from the R console (in the bottom left window):
99
-
100
-
```{r eval=FALSE}
101
-
bookdown::serve_book()
102
-
```
103
-
104
-
But which files do we edit? Well alas, it's time to discuss the file setup.
105
-
106
23
# File Setup Explanation {#file-setup}
107
24
108
25
Recall:
@@ -241,6 +158,91 @@ Bookdown makes some folders to store .html files, among other files that help cr
241
158
::::
242
159
243
160
161
+
# Opening your bookdown project in RStudio
162
+
163
+
Enter the folder you git cloned using Finder/File Explorer. It should be titled "[workshop-name]". Right click on the .Rproj file and press "Open in RStudio". There is only one file with this file extension.
**This file is what you will open each time you want to work on this workshop.** You must explicitly **open the .Rproj** file to build properly!
168
+
169
+
:::
170
+
171
+
A RStudio window should open up and look something like the image below.
172
+
\
173
+
174
+
## Explaining RStudio
175
+
176
+
In the bottom right, we have all of our files and subfolders. These files will be explained [below](#file-setup). This window also contains helpful views, like "Viewer" and "Plots". We will touch on these later.
177
+
178
+
Try opening `index.Rmd`: a new pane will open in the top left that shows the contents of `index.Rmd`. This is where we will be editing our files! Notice the "Knit" button.
179
+
180
+
In the bottom left, we have our console and other debug related windows (such as terminal!). Any code we run will appear in the console. We can access the terminal (just like editing in the Terminal app) under the "Terminal" tab.
181
+
182
+
In your top right, we have a different window with more different views. The most relevant windows to us are the "Build" and the "Git" windows.
Try closing (and maybe even restarting RStudio) and then reopening it. A "Git" tab should appear to the right of the "Build" tab and to the left of the "Tutorial" tab.
187
+
188
+
:::
189
+
190
+
## Build the Book
191
+
192
+
Try pressing "Build Book" within the "Build" window. Your build window is going to fill up with text, and soon, a website is going to pop up in a new window.
If it's your first time building, you may have to approve some downloads and installations, like we did in [the Install section](#installs).
197
+
198
+
:::
199
+
200
+
By building the book, **all** of these files are compiled and converted to .html files that create a website. Each time we make local changes to our files and we want them to appear in our website, we need to rebuild the book. Note that each time we build our book, the files we edited will be saved first - we don't have to save before building.
By default, RStudio will choose to build "All Formats":
206
+
\
207
+
You can choose to only produce a gitbook (the first option). This can be helpful if you are encountering errors claiming that "bookdown::render_book() failed to render the output format 'bookdown::pdf_book'/bookdown::epub_book'". Additionally, not producing all output formats can decrease your build time significantly.
208
+
209
+
:::
210
+
211
+
### Other Ways to Build Your Book
212
+
213
+
1. Build the book from the R console:
214
+
215
+
```{r, eval=FALSE}
216
+
bookdown::render_book()
217
+
```
218
+
219
+
2. Press the keyboard buttons: `cmd + shift + B` (macOS) OR `ctrl + shift + B` (windows)
220
+
221
+
### Knit Your Book
222
+
Building can take a long time. If you are editing just one file, you can press the "Knit" button that is at the top of the window with your file. This will run the code in the page, and show you what that page would look like in the website (as well as saving that file).
223
+
224
+
> Note: Other pages in your website will not update.
225
+
226
+
> A quicker way to knit is using the keboard controls
Building creates the website using **ALL** the .Rmd (and other) files. This is why it takes so long. Knitting creates/updates **only** the .Rmd file you're currently working in and reruns your code. (Note: You can't knit a non-.Rmd file!)
233
+
234
+
Before pushing to GitHub, it is a good idea to build, in case of faulty links or small bugs that occur if you only knit or preview.
235
+
236
+
### Preview Your Book
237
+
238
+
If you want live updates to your changes, you can preview the page as you edit the book when you save individual .Rmd files. You can start the server in a work session by using the RStudio add-in "Preview book", or from the R console (in the bottom left window):
239
+
240
+
```{r eval=FALSE}
241
+
bookdown::serve_book()
242
+
```
243
+
244
+
But which files do we edit? Well alas, it's time to discuss the file setup.
245
+
244
246
# Push to GitHub via RStudio
245
247
246
248
Now, we know what our files mean and how to edit them. How do we get this onto GitHub? We can write git commands into our Terminal/Command Prompt, or alternatively (and more easily), RStudio has a built-in git interface.
0 commit comments