In DataScienceILC/tlsc-dsfb26v-20_workflows: Bookdown site for workflows course

Lesson 4.0 - Setting up a bookdown project and publishing it online as course portfolio {#bookdownportfolio}

knitr::opts_chunk$set(echo = TRUE)

Lesson aim

After this lesson you will be able to

1. Setup github pages
2. Create a bookdown project
3. Render a bookdown project to a local website
4. Add the rendered site to your github pages

Github pages

Each account on github can be associated to one or multiple websites that are hosted on Github.com. To setup a website on Github (also called github-pages or gh-pages), we need to create a repository with a special name. For this course we will require you to upload results from the exercises and assignments results to you personal github pages. This is a hard requirement for passing this course. If you have no or an empty portfolio, you cannot pass this course

##### Exercise 4.0 1. Execute the steps explained [here](https://guides.github.com/features/pages/) to setup a github-pages repository called `workflows-portfolio` 1. Send the url to your public portfolio address to the teachers by personal chat.

Bookdown

The {bookdown} R package is basically a collection of RMarkdown files, collated into a website with nice formatting and the possibility to cross reference and add citations and visualizations. The author of the bookdown is also the main author of {knitr}.

A simple bookdown example

To start with bookdown, there is a good and free resource available.

Transform your current portfolio project to a bookdown site

By now you should have collected several Rmd files for completing the exercises and assignments in the course thusfar. If everything went well, you have these files collected in your portfolio RStudio project, linked to a Github repo. To start building your bookdown project, use the minimal example you have seen above. Start by rendering your project using bookdown::render(). To the very least you should have an index.html file that contains the yaml definitions for your bookdown project. You can arrange the chapters by using an index in every Rmd file. Use indexes like 001_<file_name>.Rmd. When you want to add a chapter in between two chapters, this makes it easier. to achieve this.

Render the book locally

When you have build your index.Rmd file and have collected all files in the root of your project, be sure all depending data, scripts and other files such as images etc. are also present in the project. Use the guerrilla analytics logic to setup the project structure. Set the option new_session: yes in your _bookdown.yml or index.Rmd file. This prevent problems down the line. Render the book until all errors are solved. You can debud each file and error by looking at the line numbers where the rendering is causing problems.

Hosting the bookdown project in your github pages

IMPORTANT NOTE ON CONFIDENTIALITY

When hosting you portfolio on a public web address, please make sure that there is no confidential information visable in your project. Data that falls under a non-disclosure agreement for example from your projecticum may not be shared. Also, be sure not to publish any personal secrets such as passwords and tokens, inside a github repo or webpage.

Once you have sucefully rendered your bookdown to a full website, hosting can be achived by copying all html files to your Github-pages. The easiest way is to clone your github pages repo and add, commit and push all html files to your github pages repo. The website will be automatically updated after some time. You can also setup a theme for your github pages. See here for more info.

For a complete manual on working with github pages, see the gh-pages docs

If you want to go for a full continuous integration workflow (which is highly recommended), you can follow these steps in this blog

DataScienceILC/tlsc-dsfb26v-20_workflows documentation built on July 4, 2025, 5:49 a.m.