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: docs/bookdown-demo.tex
+34-3Lines changed: 34 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -120,7 +120,7 @@
120
120
121
121
\title{A GitBook Example for Teaching}
122
122
\author{\href{https://www.uu.nl/staff/CJvanLissa}{dr. Caspar J. van Lissa}}
123
-
\date{2020-03-26}
123
+
\date{2020-03-28}
124
124
125
125
\begin{document}
126
126
\maketitle
@@ -129,6 +129,36 @@
129
129
\setcounter{tocdepth}{1}
130
130
\tableofcontents
131
131
}
132
+
\hypertarget{about-gitbooks}{%
133
+
\chapter{About GitBooks}\label{about-gitbooks}}
134
+
135
+
A \emph{GitBook} is a useful tool for creating (open?) educational materials. It is an online ``book'' format, that can be hosted directly from a GitHub repository. You are currently reading a GitBook designed to help you get started creating your own educational GitBooks for your courses (how meta!). It does this in two ways: By explaining how to create GitBooks, and by serving as a template that you can copy and edit, instead of having to start from scratch. This template GitBook has all the settings that I consider to be useful for educational GitBooks, but you can always customize it.
136
+
137
+
I will focus specifically on GitBooks that are made in \href{www.rstudio.com}{Rstudio}, using the \href{https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf}{\texttt{rmarkdown} markup language}, rendered using the \href{https://bookdown.org/yihui/bookdown/get-started.html}{\texttt{bookdown} package}, and hosted on \href{www.github.com}{GitHub}. \href{https://cjvanlissa.github.io/gitbook-demo/}{Here is an example of such a book}.
138
+
139
+
\hypertarget{why-use-a-gitbook-for-teaching}{%
140
+
\section{Why use a GitBook for teaching?}\label{why-use-a-gitbook-for-teaching}}
141
+
142
+
\textbf{To spead the workload}
143
+
144
+
My challenge was that I had to translate all tutorial instructions from proprietary software to R, and there was not enough time to complete this task before the course commenced. By making the tutorial instructions available in \href{https://cjvanlissa.github.io/TCSM/}{this GitBook}, I was able to continue translating tutorial instructions \emph{while the semester was ongoing}, and push updates to GitHub in time for each session, which were immediately available to all students. The parallel with the current situation is that some courses are now forced to start teaching in an online format, without having enough time to completely prepare. By using a GitBook, you can spread out the workload of preparing your materials across the semester. \href{https://cjvanlissa.github.io/TCSM/}{This is the finished GitBook}
145
+
146
+
\textbf{To contribute or use existing Open Educational Materials}
147
+
148
+
Another key advantage of using a GitBook is, that you can easily make your course materials available for others to use under an open access license, or perhaps you can use an existing GitBook from the internet and adapt it for your own uses. GitBooks can be easily duplicated and adapted, just like any other project hosted on GitHub. Contributing Open Educational Materials can help reduce the workload on teachers around the world, and can improve the quality of the materials used thanks to online collaborating and feedback.
149
+
150
+
\textbf{To benefit from formatting advantages}
151
+
152
+
GitBooks also have two formatting advantages over classic PDF or Word files. First, they are Rmarkdown files, and can thus include blocks of R (\href{https://rstudio.github.io/reticulate/articles/r_markdown.html}{or Python}) code that can be evaluated, and whose results are rendered to the file. Second, they are interactive web pages, and as such, can have dynamic features (such as answers to assignments that can be hidden, or boxes where students can fill out an answer to be checked). Additionally, other web pages or interactive apps can be embedded within the page. So whereas a traditional document is static, GitBooks can be interactive.
153
+
154
+
\textbf{How do GitBooks work?}
155
+
156
+
GitBooks consist of an Rstudio project, with several Rmarkdown files containing the chapters of the book. Inside Rstudio, users can press a ``Build Book'' button, which renders all of these chapters to a nicely formatted HTML book (and a PDF file for users to download). Users can push the finished book to a GitHub repository, and indicate on GitHub that the book should be hosted on GitHub pages. Voilà!
157
+
158
+
\textbf{Getting started}
159
+
160
+
If you are convinced that this tool might benefit your teaching, your first point of action is to prepare your system for creating GitBooks (Chapter \ref{prerequisites}). After that, you can get a copy of this GitBook as a template (Chapter \ref{getgitbook}). Then, you can start tweaking it for your own course!
<title>Chapter 3 Editing the book | A GitBook Example for Teaching</title>
7
+
<title>Chapter 4 Editing the book | A GitBook Example for Teaching</title>
8
8
<metaname="description" content="This GitBook is an example of a GitBook for teaching. It can be adapted for specific courses. The output format for this example is bookdown::gitbook." />
9
9
<metaname="generator" content="bookdown 0.17 and GitBook 2.6.7" />
10
10
11
-
<metaproperty="og:title" content="Chapter 3 Editing the book | A GitBook Example for Teaching" />
11
+
<metaproperty="og:title" content="Chapter 4 Editing the book | A GitBook Example for Teaching" />
12
12
<metaproperty="og:type" content="book" />
13
13
14
14
15
15
<metaproperty="og:description" content="This GitBook is an example of a GitBook for teaching. It can be adapted for specific courses. The output format for this example is bookdown::gitbook." />
<metaname="twitter:title" content="Chapter 3 Editing the book | A GitBook Example for Teaching" />
19
+
<metaname="twitter:title" content="Chapter 4 Editing the book | A GitBook Example for Teaching" />
20
20
21
21
<metaname="twitter:description" content="This GitBook is an example of a GitBook for teaching. It can be adapted for specific courses. The output format for this example is bookdown::gitbook." />
22
22
23
23
24
24
<metaname="author" content="dr. Caspar J. van Lissa" />
<liclass="chapter" data-level="2" data-path="get-your-gitbook.html"><ahref="get-your-gitbook.html"><iclass="fa fa-check"></i><b>2</b> Get your GitBook</a></li>
136
-
<liclass="chapter" data-level="3" data-path="editing-the-book.html"><ahref="editing-the-book.html"><iclass="fa fa-check"></i><b>3</b> Editing the book</a><ul>
137
-
<liclass="chapter" data-level="3.1" data-path="editing-the-book.html"><ahref="editing-the-book.html#creating-new-chapters"><iclass="fa fa-check"></i><b>3.1</b> Creating new chapters</a></li>
138
-
<liclass="chapter" data-level="3.2" data-path="editing-the-book.html"><ahref="editing-the-book.html#linking-across-chapters"><iclass="fa fa-check"></i><b>3.2</b> Linking across chapters</a></li>
<liclass="chapter" data-level="1" data-path="index.html"><ahref="index.html"><iclass="fa fa-check"></i><b>1</b> About GitBooks</a><ul>
135
+
<liclass="chapter" data-level="1.1" data-path="index.html"><ahref="index.html#why-use-a-gitbook-for-teaching"><iclass="fa fa-check"></i><b>1.1</b> Why use a GitBook for teaching?</a></li>
140
136
</ul></li>
141
-
<liclass="chapter" data-level="4" data-path="figtab.html"><ahref="figtab.html"><iclass="fa fa-check"></i><b>4</b> Figures and tables</a></li>
<liclass="chapter" data-level="5.1" data-path="examples.html"><ahref="examples.html#doing-meta-analysis-in-r"><iclass="fa fa-check"></i><b>5.1</b> Doing Meta-Analysis in R</a></li>
144
-
<liclass="chapter" data-level="5.2" data-path="examples.html"><ahref="examples.html#theory-construction-and-statistical-modeling"><iclass="fa fa-check"></i><b>5.2</b> Theory Construction and Statistical Modeling</a></li>
<liclass="chapter" data-level="6.1" data-path="examples.html"><ahref="examples.html#doing-meta-analysis-in-r"><iclass="fa fa-check"></i><b>6.1</b> Doing Meta-Analysis in R</a></li>
147
+
<liclass="chapter" data-level="6.2" data-path="examples.html"><ahref="examples.html#theory-construction-and-statistical-modeling"><iclass="fa fa-check"></i><b>6.2</b> Theory Construction and Statistical Modeling</a></li>
148
+
</ul></li>
149
+
<liclass="chapter" data-level="7" data-path="open-educational-resources.html"><ahref="open-educational-resources.html"><iclass="fa fa-check"></i><b>7</b> Open Educational Resources</a></li>
150
+
<liclass="chapter" data-level="8" data-path="license-your-gitbook.html"><ahref="license-your-gitbook.html"><iclass="fa fa-check"></i><b>8</b> License your GitBook</a></li>
<li><ahref="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
@@ -166,7 +170,7 @@ <h1>
166
170
167
171
<sectionclass="normal" id="section-">
168
172
<divid="editing-the-book" class="section level1">
169
-
<h1><spanclass="header-section-number">Chapter 3</span> Editing the book</h1>
173
+
<h1><spanclass="header-section-number">Chapter 4</span> Editing the book</h1>
170
174
<p>The contents of the book are written in <strong>RMarkdown</strong>. You can use any formatting code that Pandoc’s Markdown supports, e.g., a math equation <spanclass="math inline">\(a^2 + b^2 = c^2\)</span>. Moreover, you can include chunks of R-code, like this:</p>
171
175
<pre><code>```{r}
172
176
print("This is an R-command!")
@@ -176,27 +180,29 @@ <h1><span class="header-section-number">Chapter 3</span> Editing the book</h1>
176
180
<p>To edit the book, you can change the text in the <code>.Rmd</code> files. Each Rmd file should contain <strong>one and only one</strong> chapter. A chapter is defined by the first-level heading <code>#</code>, e.g., <code># Editing the book</code>.</p>
177
181
<p>Any sub-headings within the chapter are indicated with several <code>#</code> signs, e.g., <code>##</code> (level 2) and <code>###</code> (level 3).</p>
<h2><spanclass="header-section-number">3.1</span> Creating new chapters</h2>
183
+
<h2><spanclass="header-section-number">4.1</span> Creating new chapters</h2>
180
184
<p>To create a new chapter, you must follow two steps: 1) Create the file, and 2) Include it in the list of chapters.</p>
181
185
<p>First, to create the file for a new chapter in Rstudio, click <code>File > New File > Text file</code>. At the top of the file, write your chapter heading, as explained above. Then, click <code>File > Save</code>. Save the file as <code>.Rmd</code>, without spaces in the file name, e.g.: <code>editing_the_book.Rmd</code>.</p>
182
186
<p>Second, to include it in the list of chapters, open the file <code>_bookdown.yml</code> (click it in the Files explorer in the bottom right of Rstudio). This file has a list of <code>.Rmd</code> files to be included in the book. In this example, the list looks like this:</p>
<h2><spanclass="header-section-number">3.2</span> Linking across chapters</h2>
196
-
<p>You can label chapter and section titles using <code>{#label}</code> after them. The labels can be used as cross-references. For example, we can link to Chapter <ahref="figtab.html#figtab">4</a>. If you do not manually label chapters, there will be automatic labels anyway, e.g., Chapter <ahref="examples.html#examples">5</a>.</p>
201
+
<h2><spanclass="header-section-number">4.2</span> Linking across chapters</h2>
202
+
<p>You can label chapter and section titles using <code>{#label}</code> after them. The labels can be used as cross-references. For example, we can link to Chapter <ahref="figtab.html#figtab">5</a>. If you do not manually label chapters, there will be automatic labels anyway, e.g., Chapter <ahref="examples.html#examples">6</a>.</p>
<p>The convenient <ahref="https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf">Rmarkdown Cheat Sheet</a> by Rstudio covers most of the knowledge required for advanced Rmarkdown editing. You can print it out and stick it to your wall!</p>
0 commit comments