Skip to content

Latest commit

 

History

History
173 lines (110 loc) · 7.31 KB

CONTRIBUTING.md

File metadata and controls

173 lines (110 loc) · 7.31 KB
Raw

Tutorial design

  • Tutorials are centered around the concepts, complemented by how demonstrations of the concepts with actual data and code.
  • Each chapter should be readable in ~15 min. (when read by an expert)
  • Example for the level of detail and style of the tutorial: ml4ec_workshop
  • Coding style and conventions: tidyverse style guide
  • Each chapter consists of the following (high-level) sections: motivation, learning objectives, tutorial, exercises, solutions.
  • Required R libraries are kept to a minimum and dependencies to non-R libraries should be avoided. Students should be able to run all (easily) on their personal laptops.
  • Data used in the course should cover typical data types used in geography and environmental sciences:
  • FLUXNET data (time series)
  • MODIS data (MODISTools)
  • Data used in the tutorials is part of the repository and saved in the sub-directory ./data/.

Working with Bookdown

Each bookdown chapter is an .Rmd file, and each .Rmd file can contain one (and only one) chapter. A chapter must start with a first-level heading: # A good chapter, and can contain one (and only one) first-level heading.

Use second-level and higher headings within chapters like: ## A short section or ### An even shorter section.

The index.Rmd file is required, and is also your first book chapter. It will be the homepage when you render the book.

Render book

You can render the HTML version of this example book without changing anything:

  1. Find the Build pane in the RStudio IDE, and

  2. Click on Build Book, then select your output format, or select "All formats" if you'd like to use multiple formats from the same book source files.

Or build the book from the R console:

bookdown::render_book()

To render this example to PDF as a bookdown::pdf_book, you'll need to install XeLaTeX. You are recommended to install TinyTeX (which includes XeLaTeX): https://yihui.org/tinytex/.

Preview book

As you work, you may start a local server to live preview this HTML book. This preview will update 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:

bookdown::serve_book()
# automatically create a bib database for R packages
knitr::write_bib(c(
  .packages(), 'bookdown', 'knitr', 'rmarkdown'
), 'packages.bib')

Cross-references

Cross-references make it easier for your readers to find and link to elements in your book.

Chapters and sub-chapters

There are two steps to cross-reference any heading:

  1. Label the heading: # Hello world {#nice-label}.
  • Leave the label off if you like the automated heading generated based on your heading title: for example, # Hello world = # Hello world {#hello-world}.
  • To label an un-numbered heading, use: # Hello world {-#nice-label} or {# Hello world .unnumbered}.
  1. Next, reference the labeled heading anywhere in the text using \@ref(nice-label); for example, please see Chapter @ref(cross).

Captioned figures and tables

Figures and tables with captions can also be cross-referenced from elsewhere in your book using \@ref(fig:chunk-label) and \@ref(tab:chunk-label), respectively.

See Figure @ref(fig:nice-fig).

#```{r nice-fig, fig.cap='Here is a nice figure!', out.width='80%', fig.asp=.75, fig.align='center', fig.alt='Plot with connected points showing that vapor pressure of mercury increases exponentially as temperature increases.'}
par(mar = c(4, 4, .1, .1))
plot(pressure, type = 'b', pch = 19)
#```

Don't miss Table @ref(tab:nice-tab).

#```{r nice-tab, tidy=FALSE}
knitr::kable(
  head(pressure, 10), caption = 'Here is a nice table!',
  booktabs = TRUE
)
#```

Parts

You can add parts to organize one or more book chapters together. Parts can be inserted at the top of an .Rmd file, before the first-level chapter heading in that same file.

Add a numbered part: # (PART) Act one {-} (followed by # A chapter)

Add an unnumbered part: # (PART\*) Act one {-} (followed by # A chapter)

Add an appendix as a special kind of un-numbered part: # (APPENDIX) Other stuff {-} (followed by # A chapter). Chapters in an appendix are prepended with letters instead of numbers.

Footnotes and citations

Footnotes

Footnotes are put inside the square brackets after a caret ^[]. Like this one 1.

Citations

Reference items in your bibliography file(s) using @key.

For example, we are using the bookdown package [@R-bookdown] (check out the last code chunk in index.Rmd to see how this citation key was added) in this sample book, which was built on top of R Markdown and knitr [@xie2015] (this citation was added manually in an external file book.bib). Note that the .bib files need to be listed in the index.Rmd with the YAML bibliography key.

The RStudio Visual Markdown Editor can also make it easier to insert citations: https://rstudio.github.io/visual-markdown-editing/#/citations

Blocks

Equations

Here is an equation.

\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}

You may refer to using \@ref(eq:binom), like see Equation @ref(eq:binom).

Theorems and proofs

Labeled theorems can be referenced in text using \@ref(thm:tri), for example, check out this smart theorem @ref(thm:tri).

::: {#tri .theorem} For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have $$a^2 + b^2 = c^2$$ :::

Read more here https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html.

Callout blocks

The R Markdown Cookbook provides more help on how to use custom blocks to design your own callouts: https://bookdown.org/yihui/rmarkdown-cookbook/custom-blocks.html

Sharing your book

Publishing

HTML books can be published online, see: https://bookdown.org/yihui/bookdown/publishing.html

404 pages

By default, users will be directed to a 404 page if they try to access a webpage that cannot be found. If you'd like to customize your 404 page instead of using the default, you may add either a _404.Rmd or _404.md file to your project root and use code and/or Markdown syntax.

Metadata for sharing

Bookdown HTML books will provide HTML metadata for social sharing on platforms like Twitter, Facebook, and LinkedIn, using information you provide in the index.Rmd YAML. To setup, set the url for your book and the path to your cover-image file. Your book's title and description are also used.

This gitbook uses the same social sharing data across all chapters in your book- all links shared will look the same.

Specify your book's source repository on GitHub using the edit key under the configuration options in the _output.yml file, which allows users to suggest an edit by linking to a chapter's source file.

Read more about the features of this output format here:

https://pkgs.rstudio.com/bookdown/reference/gitbook.html

Or use:

#```{r eval=FALSE}
?bookdown::gitbook
#```

Footnotes

  1. This is a footnote. ↩