name: title-slide class: inverse, center, middle <style type="text/css"> .hljs-github .hljs { background: #e5e5e5; } .inline-c, remark-inline-code { background: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace; } .yellow-h{ background: #ffff88; } .out-t, remark-inline-code { background: #9fff9f; border-radius: 3px; padding: 4px; } .pull-left-c { float: left; width: 58%; } .pull-right-c { float: right; width: 38%; } .medium { font-size: 75% } .small { font-size: 50% } .action { background-color: #f2eecb; } </style> # Creating Academic Websites with R <br> ## Resul Umit ## April 2021 .footnote[ [Skip intro — To the contents slide](#contents-slide). <a href="mailto:resuluy@uio.no?subject=R Blogdown workshop">I can teach this workshop at your institution — Email me</a>. ] --- ## Who am I? Resul Umit - post-doctoral researcher at the University of Oslo - teaching and studying representation, elections, and parliaments - [a recent publication](https://doi.org/10.1177%2F1478929920967588): Parliamentary communication allowances do not increase electoral turnout or incumbents’ vote share -- <br> - teaching workshops, also on - [writing reproducible research papers](https://resulumit.com/blog/rmd-workshop/) - [version control and collaboration](https://resulumit.com/teaching/git_workshop.html) - [working with Twitter data](https://resulumit.com/syllabi/21spring_twtr.pdf) - [automated web scraping](https://resulumit.com/teaching/scrp_workshop.html) -- <br> - more information available at [resulumit.com](https://resulumit.com/) --- ## My First Website Using WordPress - opened just before starting my PhD in 2013, at [wordpress.com](https://wordpress.com/) - at first, with rare updates - none based on data - required getting used to at every login - a system that I used only for my website - then, with more frequent blogposts - frustrations with posts based on data - slow to write and edit <br> - still required getting used to at every login --- ## My Current Website Using R - migrated from WordPress in 2018 - ~~frustrations with blogposts based on data~~ - ~~slow to write and edit~~ - `blogdown` ([Xie et al., 2021a](https://cran.r-project.org/web/packages/blogdown/index.html)) makes quantitative academic writing efficient - ~~required getting used to at every login~~ - ~~a system used only for website updates~~ - a system that I use everyday for other tasks - cleaning and analysing data, writing results for publication --- ## The Workshop — Overview - One full day, on how to create websites for academics with R - building a minimal working site - version-controlling and deploying it - adding new content to the site -- <br> - Based on personalising the [example website](https://academic-demo.netlify.app/) of the `Academic` theme, with two options - using real material, creating your website now - using mock material, re-creating the [demonstration website of the workshop](https://janejdoe.netlify.app/)<sip>*</sup> - as a practice for creating your website afterwards .footnote[ <sip>*</sup> I will refer to this demonstration as <span style="background-color: #ffff88;">JJD's website</span> here, to distinguish it from the example website of the theme. ] --- ## The Workshop — Overview - One full day, on how to create websites for academics with R - building a minimal working site - version-controlling and deploying it - adding new content to the site <br> - Based on personalising the [example website](https://academic-demo.netlify.app/) of the `Academic` theme, with two options - using real material, creating your website now - using mock material, re-creating the [demonstration website of the workshop](https://janejdoe.netlify.app/) - as a practice for creating your website afterwards <br> - Designed for researchers with basic knowledge of R programming language - ability to work with R and RStudio will be very helpful - but not absolutely necessary — these skills can be developed after the workshop as well --- ## The Workshop — Motivations - Academic outreach - make your work easily accessible to other academics - keep all academic work at one address - offer versions without paywall - e.g., pre-prints -- <br> - Public outreach - make your work easily accessible to non-academics, in two senses - by removing paywalls - e.g., pre-prints <br> - by writing for non-academic audience in mind - e.g., blogposts --- ## The Workshop — Motivations — Impression Management - What do people see when they google your name? - google your name now, and scroll through - is this exactly what you want people to see? -- <br> - Websites are an impression management tool <br> - manage your online presence yourself - otherwise, others --- e.g., your (past and present) university --- will <br> - provide a concrete example of your skills - e.g., working with R, Git --- ## The Workshop — Aims - To leave you with a website - working, continuously deployed from RStudio - albeit minimal and/or mock -- <br> - To make you aware what else is possible - so that you can update your website after the workshop - awareness of what is possible, `Google`, and perseverance are all you need --- ## The Workshop — Limitations This workshop does not cover - dynamic websites - it covers [static websites](https://en.wikipedia.org/wiki/Static_web_page), as generated by `Hugo`, as integrated into R by `blogdown` - all visitors see the same website, as last generated - this setting offers what most academics would need -- - structural (HMTL, CSS, or JavaScript) customisation - e.g., changing the entire appearance and functionality of a theme, writing a new one - switching to another `Hugo` theme is an option - see 300+ options at [https://themes.gohugo.io/](https://themes.gohugo.io/) -- - multi-language or multi-author websites - these are possible, and well documented elsewhere - e.g, for multi-lingual websites, see [https://sourcethemes.com/academic/docs/language/](https://sourcethemes.com/academic/docs/language/) - e.g., for multi-author websites, see my [workshop on collaboration](https://resulumit.com/teaching/git_workshop.html#1) --- ## The Workshop — Organisation - ~~Sit in groups of two~~ - participants learn as much from their partner as from instructors - play the role of co-authors -- <br> - Type, rather than copy and paste, the code that you will find on these slides - typing is a part of the learning process - but do copy the text from [JJD's website](https://janejdoe.netlify.app/), if you are re-creating it -- <br> - When you have a question - ~~ask your partner~~ - ~~google together~~ - turn your microphone on and ask, or - type it in the chat --- class: action ## The Workshop — Organisation — Slides<sup>*</sup> - Slides with this background colour indicate that your action is required, for - setting the workshop up - e.g., installing software <br> - personalising the website - e.g., putting in your own contact details <br> - completing the exercises - e.g., adding content to your website <br> - Some of these slides have countdown timers - for guidance only .footnote[ <sup>*</sup> These slides are, and will remain, available at <https://resulumit.com/teaching/rbd_workshop.html>. ] <div class="countdown" id="timer_60b87b15" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">01</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## The Workshop — Organisation — Slides - Codes and texts that go in as input .inline-c[appear as such — in a different font, on gray background] - long codes and texts will have their own line(s) ```r ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) + geom_point(size = 2) + scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7", breaks = c(4, 6, 8)) + theme_bw() + theme(axis.title = element_text(size = 20), axis.text = element_text(size = 20), legend.title = element_text(size = 20), legend.text = element_text(size = 20)) + labs(x = "\nWeight", y = "Miles/Gallon\n") ``` --- ## The Workshop — Organisation — Slides - Codes and texts that go in as input .inline-c[appear as such — in a different font, on gray background] - long codes and texts will have their own line(s) <br> - Results that come out as output .out-t[appear as such — in the same font, on green background] - except very obvious results, such as figures and tables -- <br> - Specific sections are .yellow-h[highlighted yellow as such] for emphasis - these could be for anything — codes and texts in input, results in output, and/or texts on slides -- <br> - Names for items such as files, folders, variables are in `typefont`. - typefont with a trailing slash indicates a directory, known also as folder - e.g., `content/` is a directory --- ## The Workshop — Contents .pull-left[ [Part 1. Getting the Tools Ready](#part1) - e.g., installing software [Part 2. Website Front End](#part2) - e.g., the look in a browser [Part 3. Website Back End](#part3) - e.g., the look in RStudio [Part 4. Configuration](#part4) - e.g., overall organisation and settings ] -- name: contents-slide .pull-right[ [Part 5. Managing Structure](#part5) - e.g., organisation of pages and sections [Part 6. Deployment](#part6) - e.g., publishing your website online [Part 7. Adding Content](#part7) - e.g., adding text and images [Part 8. R Markdown](#part8) - e.g., adding tables and figures ] .footnote[ [Back to the title slide](#title-slide). [Forward to the bibliography section](#references). ] --- name: part1 class: inverse, center, middle # Part 1. Getting the Tools Ready --- class: action ## Git — Download from the Internet and Install - Git is a software that - keeps track of versions of a set of files - is .yellow-h[local] to you, the records are kept on your computer - is free -- <br> - To get this software - on Windows, install 'Git for Windows', downloading from [https://gitforwindows.org](https://gitforwindows.org/) - select 'Git from the command line and also from 3rd-party software' <br> - on Mac, install 'Git', downloading from [https://git-scm.com/downloads](https://git-scm.com/downloads) --- class: action ## GitHub — Open an Account - GitHub is a hosting service, or a website, that - keeps a copy of the versions created by Git - is .yellow-h[remote] to you, like the Dropbox website - is, mostly, free -- <br> - To sign up for this service - register an account at [https://github.com](https://github.com/) - registering an account is free - usernames are public, editable - either choose an anonymous username for now - or choose one carefully — it becomes a part of users' online presence --- class: action ## Netlify — Open an Account - Netlify is a hosting service that - builds your website out of individual files, using `Hugo` - hosts your website on its servers, making it available online - is, mostly, free -- <br> - To sign up for this service - register an account at [https://www.netlify.com](https://www.netlify.com/) - registering an account is free - you can use your GitHub account to register --- class: action ## R and RStudio — Download from the Internet and Install - R is a programming language that - does or facilitates many things, e.g., creating a website - provides the engine for RStudio — an IDE, or dashboard - is free -- <br> - Download R from [https://cloud.r-project.org](https://cloud.r-project.org) - choose the version for your operating system <br> - Download RStudio from [https://rstudio.com/products/rstudio/download](https://rstudio.com/products/rstudio/download) - choose the free version --- class: action ## R Packages — Install from within RStudio Install the following R packages, using the code below ```r install.packages(c("blogdown", "dplyr", "ggplot2")) ``` <br> - `blogdown` ([Xie et al., 2021a](https://cran.r-project.org/web/packages/blogdown/index.html)), for creating websites - comes with, among others, the `knitr` package ([Xie, 2021](https://cran.r-project.org/web/packages/knitr/index.html)), which we will use for tabling data <br> - `dplyr` ([Wickham et al., 2021](https://cran.r-project.org/web/packages/dplyr/index.html)), for data manipulation - alternatives: e.g., `base`, `data.table` ([Dowle & Srinivasan, 2021](https://cran.r-project.org/web/packages/data.table/index.html)) <br> - `ggplot2` ([Wickham et al., 2020b](-https://cran.r-project.org/web/packages/ggplot2/index.html)), for plotting data - alternatives: e.g., `base`, `plotly` ([Sievert et al., 2021](https://cran.r-project.org/web/packages/plotly/index.html)) --- ## `blogdown` — Overview - A relatively small R package, to facilitate creating websites - enables a seamless workflow, all within RStudio - does not build websites itself -- - Builds upon other software - most importantly `Hugo` for generating sites - (R) Markdown for text formatting - `pandoc` for transforming Markdown files into HTML - `YAML` syntaxes for configuration and front matter -- - Has a confusing name - it is not necessarily about blogs, but general-purpose websites -- - Comes with a book - *blogdown: Creating Websites with R Markdown* ([Xie et al., 2021b](https://bookdown.org/yihui/blogdown/)) - open access at [https://bookdown.org/yihui/blogdown/](https://bookdown.org/yihui/blogdown/) - also has a confusing name, as R Markdown is not central to creating websites --- ## `blogdown` — Addins .pull-left-c[ - Observe that, after installing `blogdown`, RStudio includes six new addins - e.g., `Serve` `Site` - mouse over in RStudio to read their definitions - Each addin has a corresponding function - e.g., `blogdown::serve_site()`<sup>*</sup> ] .pull-right-c[  ] .footnote[ [*] Not all `blogdown` functions are exported. In practice, this means we would need to call `blogdown`.yellow-h[:::] (with the triple-colon operator) for some functions, such `blogdown:::touch_file()`. ] --- ## `blogdown` — Important Fuctions - `blogdown` provides functions to facilitate interacting with `Hugo` from within R, including - `blogdown::install_hugo()` - `blogdown::serve_site()` <br> - It is customary to call `blogdown` functions with the double colon operator .yellow-h[::] - the usual way would also work - i.e., load `library(blogdown)` first <br> - To see the list of exported functions, type `blogdown::` in the `Console` - hit the `tab` key on your keyboard --- class: action ## `Hugo` — Install from within RStudio Install `Hugo`, with the following code ```r blogdown::install_hugo() ``` - `Hugo` is a .yellow-h[static] website generator - static websites are a collection of pages - pages display the same information to all visitors - It comes with - a detailed documentation, available at <https://gohugo.io/documentation/> - 300+ themes, available at <https://themes.gohugo.io/> - we will be working with the `Academic` theme --- ## Other Resources — For Later - R Markdown: The Definitive Guide (Xie et al., 2019) - open access at [https://bookdown.org/yihui/rmarkdown](https://bookdown.org/yihui/rmarkdown/) - R Markdown Cheat Sheet - follow from the RStudio menu > `Help -> Cheatsheets -> R Markdown Cheat Sheet` - Pandoc User's Guide - available at [https://pandoc.org/MANUAL.html](https://pandoc.org/MANUAL.html) - R for Data Science (Wickham and Grolemund, 2019) - open access at [https://r4ds.had.co.nz](https://r4ds.had.co.nz/) --- name: part2 class: inverse, center, middle # Part 2. Website Frontend .footnote[ [Back to the contents slide](#contents-slide). ] --- ## `Academic` — Overview .pull-left-c[ - A theme designed by [George Cushen](https://georgecushen.com/) - demonstration website is live at <https://themes.gohugo.io/theme/academic/> - documentaion is available at <https://wowchemy.com/docs/> ] .pull-right-c[  ] --- class: action ## Demonstration Sites - Visit three demonstration websites - website of the theme that we will be using, at <https://themes.gohugo.io/theme/academic> - website of this workshop that you may wish to re-create, at <https://janejdoe.netlify.app> - website of any other theme, listed at at <https://themes.gohugo.io> - Pay attention to the similarities and differences - between the websites and/or themes - between the behaviour of the menu items <div class="countdown" id="timer_60b87973" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">05</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## `Academic` — Demonstration Site - The homepage is composed of different parts, called widgets - e.g., the sections titled `Biography`, `Experience`, `Accomplishments` *etc*. -- <br> - Some menu items direct the screen to different widgets on the homepage - e.g., `Demo`, `Posts`, `Projects` *etc*. -- <br> - Other menu items direct to stand alone sections - e.g., `Courses` -- <br> - The menu also has a search function and a day/night mode switch --- ## `Academic` — Advantages - Designed especially for academics in mind - features what academics would want to feature - e.g., education, publications -- <br> - Well looked after - gets updated very frequently - `Hugo` released v0.71.1 on Monday 25 May 2020, which broke the theme - `Academic` got updated the next day with a fix - has a lively community of users and developers behind it -- <br> - Well documented - every line of code in the example site is commented in the backend - more documentation available at [https://sourcethemes.com/academic/docs/](https://sourcethemes.com/academic/docs/) --- ## `Academic` — Disadvantages - Complicated - with its high customisation, comes high complexity - its widgets can at first be overwhelming -- <br> - Popular - over 100,000 websites use this theme - hard to stand out in this crowd --- ## `Academic` — Disadvantages - Complicated **but well documented** - with its high customisation, comes high complexity - its widgets can at first be overwhelming - **you can handle it on your own** <br> - Popular **but with room for personalisation** - over 100,000 websites use this theme - hard to stand out in this crowd - **it comes with different colour schemes, fonts** - **there are many potential combinations of widgets** --- name: part3 class: inverse, center, middle # Part 3. Website Backend .footnote[ [Back to the contents slide](#contents-slide). ] --- class: action ## Website Backend — Create from within RStudio .pull-left-c[ - Create a new R project, specifically for a website > `File -> New Project -> New Directory -> Website using blogdown` - Give your project a name with `Directory Name` - Choose a location for the project with `Browse...` - synced locations, e.g., `Dropbox`, are likely to cause warning/error messages - pause syncing, or add an sync exclusion on `Dropbox` ] .pull-right-c[  ] --- class: action ## Website Backend — Create from within RStudio .pull-left-c[ - Observe that the default theme is `yihui/hugo-lithium` - this has the format `GiTHubUserName/RepoName` - located at [https://github.com/yihui/hugo-lithium](https://github.com/yihui/hugo-lithium) <br> - Change the theme to `wowchemy/starter-academic` - this is the `Academic` theme - located at <https://github.com/wowchemy/starter-academic> <br> - Click `Create Project` to start ] .pull-right-c[  ] --- ## Website Backend — Directory Structure .pull-left-c[ Observe that the .yellow-h[root directory]<sup>*</sup> is now populated with files for the theme and the example website ] .pull-right-c[  ] .footnote[ [*] The root directory is the main directory of your website project. It is often referred with a single slash .yellow-h[/]. For example .yellow-h[/config.yaml] indicates that there is a file called `config.yaml` directly under the root directory — e.i., it is not in any other sub-directory. ] --- ## Website Backend — Directory Structure .pull-left-c[ Observe that the root directory is now populated with files, including - .yellow-h[`/config.yaml`] and other configuration files under .yellow-h[`/config/`] - sets global configurations - e.g., title, decription, navigation menu - uses the YAML syntax - documented at [https://yaml.org/spec/1.2/spec.html](https://yaml.org/spec/1.2/spec.html) - will be covered [here](#yaml-syntax) later on ] .pull-right-c[  ] --- ## Website Backend — Directory Structure .pull-left-c[ Observe that the root directory is now populated with files, including - `/config.yaml`, `/config/` - .yellow-h[`/content/`] - includes files to be transformed into HTML pages - each directory under `/content/` is a section of a website - e.g., `/content/post/` can be viewed at `https://janejdoe.netlify.app/post/` ] .pull-right-c[  ] --- ## Website Backend — Directory Structure — `/content/` - Observe that the files under `/content/` are typically Markdown files - with the `.md` extension -- - These files have typically two sections - a .yellow-h[front matter] with the YAML syntax - YAML goes between a pair of three hyphens --- <br> - and some text - using Markdown syntax --- ## Website Backend — Directory Structure .pull-left-c[ Observe that the root directory is now populated with files, including - `/config.yaml`, `/config/` - `/content/` - .yellow-h[`/static/`] - contains files that should appear on websites as is - e.g., images, PDF files - these can be organised within separate directories - e.g., images can be put in `static/media/` - `Hugo` does not transform the files in this folder while generating websites ] .pull-right-c[  ] --- ## Website Backend — Directory Structure — Notes - `Hugo` websites follow more or less the same directory structure - see the `Hugo` documentation for directory structure at <https://gohugo.io/getting-started/directory-structure/> - structure might look slightly different in different themes - e.g., less complex themes have one configuration file only, without `/config/` <br> - The structure, as well as other technical details, might change - changes come with a new `Hugo` version - a change may or may not break a theme - themes are designed, and websites are generated, with a certain version - these two versions do not have to be the same, but compatible --- class: action ## Website Backend — Set `Hugo` Version Set `blogdown.hugo.version` in `/.Rprofile` to the latest `Hugo` version that you have - `Hugo` version in `/.Rprofile` is often out of date - first check the installed `Hugo` versions that you have - by running `blogdown::find_hugo("all")` in the `Console` <br> - changes to `.Rprofile` take affect only after saving the file, and restarting R - after saving, follow `Session -> Restart R` --- class: action ## Website Backend — `Serve` `Site` .pull-left-c[ - Click the `Addins` `->` `Serve` `Site` to preview the site - this is equivalent to typing `blogdown::serve_site()` in the `Console` - Observe that the website is live in the `Viewer` tab - this can be viewed with a browser, by clicking on the window icon ] .pull-right-c[ <img src="rbd_workshop_files/images_data/viewer.png" width="100%" /> ] --- class: action ## Website Backend — `Serve` `Site` .pull-left-c[ - Click the `Addins` `->` `Serve` `Site` to preview the site - this is equivalent to typing `blogdown::serve_site()` in the `Console` - Observe that the website is live in the `Viewer` tab - this can be viewed with a browser, by clicking on the window icon ] .pull-right-c[ <img src="rbd_workshop_files/images_data/browser.png" width="100%" /> ] --- class: action ## Website Project — `Serve Site` .pull-left-c[ - Click the `Addins -> Serve Site` to preview the site - this is equivalent to typing `blogdown::serve_site()` in the `Console` - Observe that the website is live in the `Viewer` tab - this can be viewed with a browser, by clicking on the window icon - You can make live edits in this state - e.g., in `/config.yaml`, change <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">title = "Academic"</span>, and save - e.g., to <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">title = "YourName"</span> - observe the live change in the website ] .pull-right-c[ <img src="rbd_workshop_files/images_data/viewer2.png" width="100%" /> ] --- name: part4 class: inverse, center, middle ## Part 4. Configuration .footnote[ [Back to the contents slide](#contents-slide). ] --- ## Configuration — Overview - There are four configuration files in the theme - `/config.yaml` - `/config/_default/languages.yaml` - `/config/_default/menus.yaml` - `/config/_default/params.yaml` -- <br> - These files are for overall definitions, settings, and organisation - e.g., creating menu items; defining font, language - these files are written with the YAML syntax -- <br> - We will work with the existing options of in these files - for the complete list of options that you can use in configuration files, see <https://gohugo.io/getting-started/configuration> --- name: yaml-syntax ## Configuration — YAML Syntax .pull-left[ - YAML uses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">key: value</span> pairs - keys are pre-defined — mostly by `Hugo`, but also by each theme - e.g., `title` - users supply the values - e.g., "Name Surname" ] .pull-right[ ```r title: "Jane J. Doe" ``` ] --- ## Configuration — YAML Syntax .pull-left[ - YAML uses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">key: value</span> pairs - keys are pre-defined — mostly by `Hugo`, but also by each theme - e.g., `title` - users supply the values - e.g., "Name Surname" - Values can take - <span style="background-color: #ffff88;">strings</span><span>*</span> ] .pull-right[ ```r `title: "Jane J. Doe"` ``` ] .footnote[ <span>*</span> String do not need quotation marks unless they include special characters, such as a colon. Once I spent half a day trying to understand why my website would not build, only to figure this nuance out. I therefore recommend using quotations marks for all strings, just in case. ] --- ## Configuration — YAML Syntax .pull-left[ - YAML uses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">key: value</span> pairs - keys are pre-defined — mostly by `Hugo`, but also by each theme - e.g., `title` - users supply the values - e.g., "Name Surname" - Values can take - strings, in quotation marks - <span style="background-color: #ffff88;">numbers, bare</span> ] .pull-right[ ```r title: "Jane J. Doe" `summaryLength: 30` ``` ] --- ## Configuration — YAML Syntax .pull-left[ - YAML uses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">key: value</span> pairs - keys are pre-defined — mostly by `Hugo`, but also by each theme - e.g., `title` - users supply the values - e.g., "Name Surname" - Values can take - strings, in quotation marks - numbers, bare - <span style="background-color: #ffff88;">Boolean values, in lower case, bare</span> ] .pull-right[ ```r title: "Jane J. Doe" summaryLength: 30 `enableEmoji: true` ``` ] --- ## Configuration — YAML Syntax .pull-left[ - YAML uses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">key: value</span> pairs - keys are pre-defined — mostly by `Hugo`, but also by each theme - e.g., `title` - users supply the values - e.g., "Name Surname" - Values can take - strings, in quotation marks - numbers, bare - Boolean values, in lower case, bare - <span style="background-color: #ffff88;">sequence of values with a hyphen each</span> ] .pull-right[ ```r title: "Jane J. Doe" summaryLength: 30 enableEmoji: true `interests:` `- Party politics` `- Public policy` `- International polities` ``` ] --- ## Configuration — YAML Syntax — Notes There is an alternative way to write sequence of values - in square brackets, separated by comma ```r title: "Jane J. Doe" summaryLength: 30 enableEmoji: true `interests: [Party politics, Public policy, International polities]` ``` --- ## Configuration — YAML Syntax — Notes Multiple nesting of keys and sequences is also possible - requires indentation with four spaces for the first nesting, and an hyphen for the second ```r education: ` `courses: ` - `course: PhD in Political Science institution: University of Vienna year: 2017 ` - `course: MSSc in European Studies institution: University of Tampere year: 2009 ``` --- ## Configuration — YAML Syntax — Notes To disable an option in YAML, you can - comment its line out with a hash ```r # title: "Jane J. Doe" ``` -- - set it to `[]` - this may not work in nests ```r title: [] ``` -- - set it to "" ```r title: "" ``` -- - delete it altogether - not recommended, as you might need that key in the future ```r ``` --- class: action ## Exercises — Configuration — `/config.yaml` - Edit one or more values in the `/config.yaml` file - locate the file under the root directory - edit at least the `title` and `copyright`<sup>*</sup> keys, with - your information, or - information on [JJD's website](https://janejdoe.netlify.app/) <br> - remember to save the file - and observe the changes in the RStudio Viewer and/or on a browser <br> - Scroll through the other keys - to see what else is available that you may wish to edit - once your website is online, you should also edit `baseurl` in this file - remember to keep the trailing slash - e.g. https://janejdoe.netlify.app<span style="background-color: #ffff88;">/</span> .footnote[ <sup>*</sup> `©` is the HTML code for the copyright symbol <span style="background-color: #ffff88;">©</span>. `{year}` turns into the current year, so that you don't have to update this every year. ] <div class="countdown" id="timer_60b878bd" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">05</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- class: action ## Exercises — Configuration — `params.yaml` - Edit one or more values in the `params.yaml` file - locate it under `/config/_default/` - edit at least the values for contact details - observe the changes in the RStudio Viewer and/or on a browser <br> - Scroll through the other keys in other sections - colour schemes and fonts are defined in this file as well - an important opportunity to personalise - see what is available at <https://sourcethemes.com/academic/themes/> <br> - icons are available from various packages - see the list at <https://sourcethemes.com/academic/docs/page-builder/#icons> <div class="countdown" id="timer_60b87961" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">15</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Configuration — `menus.yaml` This file configures the website menu - creates and orders menu items - directs them - to a specific section on the homepage - e.g., to a widget such as Contact at the bottom of the homepage <br> - to a specific page - e.g., to a page that lists the titles of all blogposts - e.g., to a specific blogpost --- ## Configuration — `menus.yaml` .pull-left-c[ - Define menu items - as a list, with the `name` argument ] .pull-right-c[ ```r main - `name`: "Posts" - name: "Courses" - name: "Twitter" - name: "CV" ``` ] --- ## Configuration — `menus.yaml` .pull-left-c[ - Define menu items - Order the items - with the `weight` argument <br> - Note that - the order, not the actual value, matters - you could use 1, 4, 9 ... instead <br> - using the same value for two or more items should be avoided ] .pull-right-c[ ```r main - name: "Posts" `weight`: 10 - name: "Courses" weight: 30 - name: "Twitter" weight: 20 - name: "CV" weight: 40 ``` ] --- ## Configuration — `menus.yaml` .pull-left-c[ - Define menu items - Order the items - Link them to destinations - with the `url` argument <br> - with a number sign <span style="background-color: #ffff88;">#</span> to a widget on the homepage - these match a file name under `/content/home/` <br> - with a trailing slash <span style="background-color: #ffff88;">/</span> to sections - these match a file or folder name under `/content/` <br> - with URLs to external sites - e.g., Twitter <br> - with paths relative to the `/static/` sub-directory - `files/cv.pdf` suggests cv is under `/static/files/cv.pdf` ] .pull-right-c[ ```r main: - name = "Posts" weight = 10 `url = "#posts"` - name = "Courses" weight = 30 `url = "courses/"` - name = "Twitter" weight = 20 `url = "https://twitter.com/resulumit"` - name = "CV" weight = 40 `url = "files/cv.pdf"` ``` ] --- class: action ## Exercises — Configuration — `menus.yaml` - Edit the `menus.yaml` file, as much as possible now<sup>*</sup> - create, order, and direct menu items - observe the changes in the RStudio Viewer and/or on a browser .footnote[ <sup>*</sup> You are likely to edit this file throughout the workshop, as your website evolves. ] <div class="countdown" id="timer_60b878d2" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">05</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Configuration — `languages.yaml` This file - defines the language of the website - the default is English - can make the site multi-lingual - we will not cover it in this workshop - instructions available at the above link as well --- ## Configuration — Multi-lingual Sites - Considerations <br> - who is your target audience? - would they be lost if your website was only in one language? - if not, perhaps it is not worth the hassle <br> - what will be in multiple languages? - all website, or some widgets and/or pages? - even in a single language setting, widgets and pages can be written in different languages -- <br> - Strategy - build your website in full in one language first, than add the second - rather then building it multiple languages in tandem - hence not covered in the workshop --- class: action ## Exercises — Configuration — `languages.yaml` - This exercise is optional - only if your preferred language is not English - see the list of language options and their codes at <https://wowchemy.com/docs/guide/language/> <br> - Change the langauge of your website, in two steps - in `languages.yaml`: - provide a different value to the `languageCode` key <br> - in `/config.yaml`: - edit the value for `defaultContentLanguage` <div class="countdown" id="timer_60b87a9d" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">03</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- name: part5 class: inverse, center, middle ## Part 5. Managing Structure .footnote[ [Back to the contents slide](#contents-slide). ] --- ## Structure — Overview - Structure depends mostly on the way the `/content/` directory is organised, including - individual pages, such as a homepage - sections (collections of pages), such as a blog <br> - Each page at the fronted corresponds to a Markdown file at the backend - changing the content and/or the position of these files at the backend will change the frontend <br> - Sections are organised in separate directories under `/content/` - first-level sub-directories become a section by default - e.g. `content/post/` is a section (for all blogposts) <br> - creating a section under a section requires manual input - by adding a file named `_index.md` under the second-level directory --- ## Structure — Examples A website with a single page ```r . └── /content/ | └── home.md # <- https://janejdoe.netlify.app/home/ ``` --- ## Structure — Examples A website with two single pages ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/home/ | └── `about.md` # <- https://janejdoe.netlify.app/about/ ``` --- ## Structure — Examples A website with five pages ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/home/ | ├── about.md # <- https://janejdoe.netlify.app/about/ | └── `blog/` # <- https://janejdoe.netlify.app/blog/ | ├── `first-post.md` # <- https://janejdoe.netlify.app/blog/first-post/ | └── `second-post.md` # <- https://janejdoe.netlify.app/blog/second-post/ ``` Note that there are - four single pages: home, about, first-post, second-post - one section page: blog - because it is a first order sub-directory - by default, this section page is tiled Blog, showing the links to the two posts --- ## Structure — Examples A website with three pages ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/home/ | ├── about.md # <- https://janejdoe.netlify.app/about/ | └── `blog/index.md` # <- https://janejdoe.netlify.app/blog/ ``` <br> Note that - `index.md` is a special file name for `Hugo` — it creates a page matching its directory name - there are three single pages: home, about, blog - blog is not a section page, but a simple page, showing a blogpost --- ## Structure — Examples A website with five pages: three three single pages and two nested section pages ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/`home`/ | └── blog/ # <- https://janejdoe.netlify.app/`blog`/ | ├── first-post.md # <- https://janejdoe.netlify.app/blog/`first-post`/ | └── academic/ # <- https://janejdoe.netlify.app/blog/`academic`/ | ├── _index.md | └── second-post.md # <- https://janejdoe.netlify.app/blog/academic/`second-post`/ ``` --- ## Structure — Examples A website with five pages: .yellow-h[three single pages] and two nested section pages ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/`home`/ | └── blog/ # <- https://janejdoe.netlify.app/blog/ | ├── first-post.md # <- https://janejdoe.netlify.app/blog/`first-post`/ | └── academic/ # <- https://janejdoe.netlify.app/blog/academic/ | ├── _index.md | └── second-post.md # <- https://janejdoe.netlify.app/blog/academic/`second-post`/ ``` --- ## Structure — Examples A website with five pages: three single pages and .yellow-h[two nested section pages] ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/home/ | └── blog/ # <- https://janejdoe.netlify.app/`blog`/ | ├── first-post.md # <- https://janejdoe.netlify.app/blog/first-post/ | └── academic/ # <- https://janejdoe.netlify.app/`blog/academic`/ | ├── _index.md | └── second-post.md # <- https://janejdoe.netlify.app/blog/academic/second-post/ ``` --- ## Structure — Examples A website with five pages: three single pages, .yellow-h[two nested section pages] ```r . └── /content/ | ├── home.md # <- https://janejdoe.netlify.app/home/ | └── blog/ # <- https://janejdoe.netlify.app/blog/ | ├── first-post.md # <- https://janejdoe.netlify.app/blog/first-post/ | └── academic/ # <- https://janejdoe.netlify.app/`blog/academic`/ | ├── `_index.md` | └── second-post.md # <- https://janejdoe.netlify.app/blog/academic/second-post/ ``` Notice that - `_index.md`, with underscore, is a special file name for `Hugo` — it creates sections --- ## Structure — Examples Having `_index.md` in first-order sub-directories is optional, but may be helpful - can add metadata and/or text to section pages - e.g., these are by default titled as the plural of section names - e.g., the page `publication/` is titled as `Publications` - change this behaviour with `_index.md` ```r . └── /content/ | └── home.md # <- https://janejdoe.netlify.app/home/ | └── about.md # <- https://janejdoe.netlify.app/about/ | └── `blog/` # <- https://janejdoe.netlify.app/blog/ | ├── `_index.md` | ├── first-post.md # <- https://janejdoe.netlify.app/blog/first-post/ | └── second-post.md # <- https://janejdoe.netlify.app/blog/second-post/ ``` --- class: action ## Exercises — Structure - Explore the directory structure of your website in RStudio - how many pages and sections are there? - are there any subsections? - hint: see `courses/` <br> - Do a matching exercise - open the example site on a browser - try and find the front end of the following file - `/content/publication/journal-article/index.md` <br> - compare the back end with front end <div class="countdown" id="timer_60b87bbb" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">05</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Structure — `home/` — Overview - The homepage in `Academic` does not exactly follow the structure above - every file under `home/` is not a stand alone page - these files, called widgets, are rather stitched under one another - considered as one of the strengths of the theme - some academics prefer to have only this page -- <br> - Widgets are complicated Markdown files - can be stitched under one another - can get text from files elsewhere - e.g., the `contact.md` widget gets the address information from `params.yaml` -- <br> - A homepage can have one, more, or all widgets - widgets can be deactivated or repeated - they can be re-ordered as well --- ## Structure — `home/` — Widgets - There are 13 types of pre-defined widgets - for detailed explanations, see [https://sourcethemes.com/academic/docs/page-builder/](https://sourcethemes.com/academic/docs/page-builder/) - you can build your own widget as well -- <br> - Widgets are in fact Markdown files, with .md extension - each has YAML syntax as the front matter - some has Markdown text as well - e.g., `demo.md` - because they can have both variables and text, YAML goes between a pair of three hashes -- <br> - Widgets are located under `/content/home/` - except `index.md`, each file is a widget — some duplicates of the same type --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - <span style="background-color: #ffff88;">Indicate the type of the widget</span> - see all pre-defined types at <https://sourcethemes.com/academic/docs/page-builder/> ] .pull-right-c[ ```r `widget: "pages"` ``` ] --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - Indicate the type of the widget - <span style="background-color: #ffff88;">De-activate a widget</span> ] .pull-right-c[ ```r widget: "pages" `active: false` ``` ] --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - Indicate the type of the widget - De-activate a widget - <span style="background-color: #ffff88;">Order a widget in relation to other widgets</span> ] .pull-right-c[ ```r widget: "pages" active: false `weight: 9` ``` ] --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - Indicate the type of the widget - De-activate a widget - Order a widget in relation to other widgets - <span style="background-color: #ffff88;">Title and/or subtitle it</span> ] .pull-right-c[ ```r widget: "pages" active: false weight: 9 `title: "Recent Publications"` `subtitle: ""` ``` ] --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - Indicate the type of the widget - De-activate it - Order it in relation to other widgets - Title and/or subsitle it - Some keys are widget specific - <span style="background-color: #ffff88;">Link it to a content section</span> ] .pull-right-c[ ```r widget: "pages" active: false weight: 9 title: "Recent Publications" subtitle: "" `page_type: "publication"` ``` ] --- ## Structure — Homapage — Widgets — Important Keys .pull-left-c[ - Some keys are common across all widgets - Indicate the type of the widget - De-activate it - Order it in relation to other widgets - Title and/or subsitle it - Some keys are widget specific - <span style="background-color: #ffff88;">Link it to a content section</span> - Widgets in the example site come with many keys and detailed definitions - further documentation is available at <https://sourcethemes.com/academic/docs/page-builder/> ] .pull-right-c[ ```r widget: "pages" active: false weight: 9 title: "Recent Publications" subtitle: "" `page_type: "publication"` ``` ] --- ## Structure — Adding - There are at least three ways to add new pages and sections - create new files and directories, respecting the directory structure of `Hugo` and `Academic` - rename and edit the existing files and folders for your purposes - duplicate, rename, and edit the existing files and folders that are in use <br> - RStudio has helpful buttons for these purposes - to create, duplicate, and/or rename - alternatively, use your operating system --- class: action ## Exercises — Structure — Adding Rename one or more blogposts and publications on your website - observe the changes in RStudio Viewer <br> Hint: - this exercise is about structure, not the content - we will cover editing the content in [Part 8](#part8) and [Part 9](#part9) <br> - JJD's website has the following - two blogposts - <https://janejdoe.netlify.app/post/academic-websites/> - <https://janejdoe.netlify.app/post/cabinet-size/> <br> - two publications - <https://janejdoe.netlify.app/publication/parties-politics/> - <https://janejdoe.netlify.app/publication/parties-social-media/> <div class="countdown" id="timer_60b87813" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">10</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Structure — Removing There are at least two ways to remove pages and sections - delete them, respecting the directory structure of `Hugo` and `Academic` - perhaps, you are sure there will not be two authors on your website - the example site comes with two author profiles, under `/content/authors/` - with usernames `admin` (main) and `吳恩達` (secondary) - it is safe to delete the latter <br> - turn them into drafts, by setting - <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">active: false</span> in the YAML of widgets - <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">draft: true</span> in the YAML of other Markdown files - perhaps, you think you may need a section in the future --- class: action ## Exercises — Structure — Removing — Widgets - Keep only the widgets that you would like to have on your website - set <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">active: false</span> in the front matter of the undesired widget - re-order the desired widgets if necessary - check if the homepage looks and works as expected <br> - Hint: - `/content/home/index.md` is not a widget - although it is under the same directory with all widgets <br> - on [JJD's website](https://janejdoe.netlify.app/), the following widgets are active - hero, about, experience, publications, posts, contact <br> - you may need to configure the menu in parallel - by editing `/config/_default/menus.yaml` <div class="countdown" id="timer_60b879d8" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">10</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Structure — Removing — Non-Widget Markdown - You can deactivate a specific page in a section - add <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">draft: true</span> to file of that page - e.g., `/content/publication/journal-article/index.md` <br> - You can deactivate whole sections in one go - add <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">draft: true</span> to file of that section - e.g., `/content/publication/_index.md` <br> - You can deactivate whole sections except one or more pages - add <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">draft: true</span> to file of that section - e.g., `/content/publication/_index.md` <br> - add <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">draft: false</span> to the file of a page - e.g., `/content/publication/journal-article/index.md` --- ## Structure — Removing — Non-Widget Markdown - Not all sections have `_index.md` to start with - e.g., `/content/project/` - you can add one, following > `File -> New File -> R Script` <br> - Draft pages and sections are still visible to you in live preview - e.i., when you use `blogdown::serve_site` - but not to the visitors of your website - e.i., if you publish your site --- class: action ## Exercises — Structure — Non-Widget Markdown - Keep only the sections and pages that you would like to have on your website - set the `draft` key to `true` or `false` in the front matter of relevant files - check if the website looks and works as expected <br> - Hint: - on [JJD's website](https://janejdoe.netlify.app/), the following sections are active - home, authors, post, publication - `admin` is the only author <br> - you may need to configure the menu in parallel - by editing `/config/_default/menus.yaml` <div class="countdown" id="timer_60b87b4f" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">10</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- name: part6 class: inverse, center, middle # Part 6. Deployment .footnote[ [Back to the contents slide](#contents-slide). ] --- ## Deployment — Overview - Deployment of your website onto a web server makes it visible online - your website is currently available on your computer only <br> - You can deploy your website at any web server that you prefer - [Netlify](https://www.netlify.com/) is a popular choice as a web server - easy to set up - includes a free plan - recommended by the authors of the `blogdown` package and the `Academic` theme --- ## Deployment — Workflow Deployment occurs in two steps - we push the website files, from our computer, into a GitHub repository - for the first time, and after one or more edits - with commands or clicks in RStudio <br> - Netlify does the rest automatically, in a minute or so - (re-)retrieves the files - generates the website with `Hugo` - (re-)publishes the website --- ## Deployment — Git and GitHub — Definitions - Git - a software that keeps track of versions of a set of files - it is local, the records are kept on your computer -- - GitHub - a hosting service, or a website, that can keep the records - it is like Dropbox, but specifically structured to keep records with Git -- - Repository, or repo - a set of files whose records are kept together, by Git and/or on GitHub - it is like a folder, which can keep files and other folders containing files --- ## Deployment — Git and GitHub — Definitions - To commit - to take a snapshot of, to version a repository - it is like saving a new version of all changed files in your folder with a new name - it is local, the records are kept on your computer unless you `push` -- - To push - to move the records from Git to GitHub, from your computer to online - it is like uploading (the new versions of) your files to a website, - it also involves merging, if this not the first push -- - To pull - to move the updated records from GitHub to your computer - it is like downloading a zipped folder of files, and merging with the ones on your computer --- ## Deployment — Git and GitHub — Workflow Working with with Git and GitHub requires - .yellow-h[initial setup], done once<sup>*</sup> - unless for a new computer or, if ever, a new GitHub account - a bit technical, but worth the hassle <br> - .yellow-h[project setup], repeated for every RStudio project - shorter, less complicated .footnote[ [*] We have started this process already, in [Part 1](#part1) of the workshop, by downloading and installing Git and signing up for GitHub. ] --- class: action ## Deployment — Git and Github — Inital Setup 1) Enable version control with RStudio - from the RStudio menu, follow: > `Tools -> Global Options -> Git/SNV -> Enable version control interface for RStudio projects` - RStudio will likely find Git automatically. In case it cannot, Git is likely to be at - `c:/Program Files/Git/bin/git.exe` on Windows - `/usr/local/git/bin/git` on Mac --- class: action ## Deployment — Git and Github — Inital Setup 2) Set Git Bash as your shell (Windows-only step) - from the RStudio menu, follow: > `Tools -> Global Options -> Terminal -> New terminals open with: Git Bash` --- class: action ## Deployment — Git and Github — Inital Setup 3) Introduce yourself to Git - from the RStudio menu, follow: > `Tools -> Terminal -> New Terminal` <br> - enter the following lines in the Terminal - replacing the relevant parts with .yellow-h[your personal information] - e.g., the email address that you have used to sign up for GitHub ```yaml git config --global user.name `"YOUR NAME"` git config --global user.email `"YOUR EMAIL ADDRESS"` ``` <br> - enter the following line in the Terminal - to observe whether the previous step was successful ```yaml git config --global --list ``` --- class: action ## Deployment — Git and Github — Project Setup 1) Initiate local version control with Git - from the RStudio menu, follow: > `Tools -> Version Control -> Project Setup... -> Version Control System -> Git` <br> - after confirming your new repository, and restarting the session, observe that - now there is now a Git tab in RStudio, - documenting the differences between you local repository and the one on GitHub - when you change a file, it will appear here <br> - your project now includes a `.gitignore` file - this is where you can list files and/or folders to be excluded from being tracked --- class: action ## Deployment — Git and Github — Project Setup 2) Create a new GitHub repository - on GitHub, follow: > `Repositories -> New -> Repository name (e.g., "my_website") -> Public -> Create repository` <br> - observe that - repository URLs have the following structure: https://github.com/USER_NAME/REPOSITORY_NAME - this is the address to view the repository online - for use in the `Terminal`, the address gets the `.git` extension - e.g., https://github.com/USER_NAME/REPOSITORY_NAME.git --- class: action ## Version Control — Git and Github — Project Setup 3) Push an existing repository - from the RStudio menu, follow: > `Tools -> Terminal -> New Terminal` - enter the following lines in the `Terminal` - with .yellow-h[your] username and repository name ```yaml git remote add origin https://github.com/`USER_NAME/REPOSITORY_NAME`.git git add . git commit -m "initial commit" git push -u origin master ``` <br> - Notice that - your files are now online at your GitHub repository - we have completed the first step in deployment --- class: action ## Deployment — Netlify — Setup 1) After logging in to Netlify, follow > `New site from Git -> GitHub` <br> - complete the authorisation process - so that GitHub allows Netlify to access your repository - once completed, pick your repository from the list, and click `Deploy site` - the default settings should work --- class: action ## Deployment — Netlify — Setup 2) While on the `Site overview` page, click on `Domain settings` - change the name of your site to something more meaningful - by default, Netlify assigns a random name - e.g., hus324n.netlify.app <br> - if you have a custom domain name - e.g., you have purchased yournamesurname.com - click on `Add custom domain` and follow the instructions <br> - if you don't have a custom domain name, - click on `Options` to change the random address to something more meaningful - e.g., yournamesurname.netlify.app --- class: action ## Deployment — Workflow — In Practice 1) In RStudio, edit your site with the its URL - this is done through the `baseurl` key in `/config.yaml` - set it to `https://yournamesurname.netlify.app/` - including the trailing slash - observe whether the site still builds, in Viewer <br> 2) Commit and Push - under the Git tab in RStudio, find the file - it will have `M`, for modified, as `Status` <br> - tick `Staged`<sup>*</sup> for that file, and click `Commit` - enter a `Commit message` that summarises the edit - click `Commit` to create a record of the new version locally to your computer - click `Close -> Push` to push the version to GitHub .footnote[ [*] To stage is to add files to be committed. It allows us to commit one or more files together or separately. ] --- ## Deployment — Notes - Avoid pushing your project to GitHub without checking it works locally first - use `blogdown` for your advantage, observe it in Viewer -- <br> - If things still go wrong, you can revert back to the version on GitHub - `git checkout HEAD PATH/TO/FOLDER/OR/FILE` reverts a specific folder or file - `git reset --hard` reverts all -- <br> - Note that - reverting as above gets rid of good as well as bad edits - more nuanced approaches are possible - reverting further back to one of the previous versions also possible - see my [workshop materials on working with with Git and GitHub](https://resulumit.com/teaching/git_workshop.html) for more information --- class: action ## Exercises — Deployment - Practice deployment one more time - edit a piece of text that is visible on your website, and save - e.g., the `title` key in `/config.yaml` <br> - observe the change locally, in Viewer - stage, commit, push - observe the change online, in a browser <div class="countdown" id="timer_60b87a77" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">03</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- name: part7 class: inverse, center, middle # Part 7. Adding Content .footnote[ [Back to the contents slide](#contents-slide). ] --- ## Content — Overview Most of what is visible at website frontend is stored in three directories at the backend - some files are under the `/assets/` directory - most importantly, the website icon <br> - other display-as-is materials are under the `/static/` directory - e.g., PDFs, images <br> - most materials are under the `/content/` directory - e.g., Markdown files matching pages, widgets for the homapage --- ## Content — `/assets/` - This directory stores non-textual files to be processed - by `Hugo` to generate the website - e.g., images <br> - By default, files under `/assets/` do not have a matching URL - visitors will not be able to view them unprocessed on a browser <br> - Adding a file to `/assets/` is straightforward - move or copy into it as normal <br> - `Academic` looks in `/assets/media/` for a website icon - it appears, e.g., on web browser tabs - it must be named `icon.png` - if not, `Academic` uses the default icon --- class: action ## Exercises — Content — `/assets/` Change your website icon - by placing an image named `icon.png` to `/assets/media/` - stage, commit, push - observe the change online, in a browser <br> Hint: - website icons are not visible in RStudio Viewer - images are best saved as a square 512x512 pixel - JJD's icon is the same as her profile picture - available for [download here](https://github.com/resulumit/workshop_website/raw/master/assets/media/icon.png) <div class="countdown" id="timer_60b8797a" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">03</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Content — `/static/` - This directory stores non-textual files .yellow[not] to be processed - `Hugo` simply copies these files over to frontend - e.g., images -- <br> - By default, files under `/static/` have a matching URL - visitors will be able to view them unprocessed on a browser ```r . └── /static/ | └── pfofile-photo.jpg # <- https://janejdoe.netlify.app`/`pfofile-photo.jpg | └── `files/` | └── cv.pdf # <- https://janejdoe.netlify.app/`files`/cv.pdf ``` --- ## Content — `/static/` - This directory stores non-textual files .yellow[not] to be processed - `Hugo` simply copies these files over to frontend - e.g., images <br> - By default, files under `/static/` have a matching URL - visitors will be able to view them unprocessed on a browser <br> - Adding a file to `/static/` is straightforward - move or copy into it as normal <br> - `/static/` is the right directory to store PDFs - e.g., cv, publications --- class: action ## Exercises — Content — `/static/` Make one or more files available as-is on your website - by placing them under `/static/` - directly, or under a sub-directory - stage, commit, push - observe the change online, in a browser <br> Hint: - static files are not visible in RStudio Viewer - [JJD's website](https://janejdoe.netlify.app/) has her cv and two publications available to view as-is - download them from her website <div class="countdown" id="timer_60b879f4" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">05</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- ## Content — `/content/` - This directory stores mostly textual files to be processed - mostly by `Hugo`, some by `blogdown` - e.g., Markdown files <br> - Most files under this directory are .yellow-h[plain] Markdown files - with the `.md` extension - transformed by `Blackfriday` — `Hugo`'s Markdown rendering engine, so is Netlify's — into HTML - no need for `blogdown`, but cannot execute any code <br> - Some are .yellow-h[R] Markdown files - with either `.Rmd` or `.Rmarkdown` extension - transformed by `pandoc` — `blogdown`'s rendering engine - therefore can execute code, thanks to `blogdown` - we will cover these in [Part 8](#part8) --- ## Content — Markdown Syntax — Overview - Markdown is a plain-text file - with its own syntax - much easier to write than HTML - the differences between plain and R Markdown syntaxes are minimal - versatile, can be transformed into many different formats, including HTML -- <br> - Plain Markdown (`.md`) follows `Blackfriday`'s Markdown syntax - a useful guide to the basic MArkdown syntax is available at <https://www.markdownguide.org/basic-syntax/> - a small number of `Blackfriday`-specific extensions are available at <https://github.com/russross/blackfriday> <br> - R Markdown (`.Rmd` and `.Rmarkdown`) follows the syntax in Pandoc's Markdown - for the complete rules of the syntax, see [Pandoc User's Guide](https://pandoc.org/MANUAL.html) - for a useful summary of the syntax, see the R Markdown Cheat Sheet --- ## Content — Markdown Syntax — Strategies - There are at least two different strategies to deal with `.md` versus `.Rmd` dilemma - use `.md` for pages with no data, `.Rmd` for pages with data - maximises the functionality from each - requires learning the small differences if necessary - use `.Rmd` for all pages - requires learning only one syntax - misses the additional functionality in `.md` - folders get cluttered with intermediate files -- <br> - The syntax in the following slides of this section will work with both types - unless otherwise stated - e.g., see [tasks lists](#task-lists) --- ## Content — Markdown Syntax — Lines Multiple spaces on a given line are reduced to one ```r This is a sentence followed by four spaces. This is another sentence on the same line. ``` .out-t[This is a sentence followed by four spaces. This is another sentence on the same line.] <br> Line endings with fewer than two spaces are ignored ```r This is a sentence followed by one space. This is another sentence on a new line. ``` .out-t[This is a sentence followed by one space. This is another sentence on a new line.] --- ## Content — Markdown Syntax — Hard Brakes Two or more spaces at the end of lines introduce hard brakes, forcing a new line ```r This is a sentence followed by two spaces. This is another sentence on a new line. ``` .out-t[This is a sentence followed by two spaces. This is another sentence on a new line.] --- ## Content — Markdown Syntax — Block Quotes Lines starting with the grater-than sign .yellow-h[>] introduce block quotes ```r > In God, we trust. All others must bring data. > > --- Anonymous ``` .out-t[ In God, we trust. All others must bring data. — Anonymous ] --- ## Content — Markdown Syntax — Paragraphs One or more<sup>*</sup> blank lines introduce a new paragraph ```r This is the first sentence of a paragraph as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. This is the first sentence of a *new paragraph* as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. ``` .out-t[ This is the first sentence of a paragraph as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. This is the first sentence of a *new paragraph* as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. ] .footnote[ [*] Multiple blank lines between paragraphs reduced to one. ] --- ## Content — Markdown Syntax — Comments Text with the syntax .inline-c[<!--].inline-c[comments -->] is omitted from output ```md <!-- This paragraph needs re-writing --> This is the first sentence of a paragraph as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. This is the first sentence of a new paragraph <!-- I've removed italics --> as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. ``` .out-t[ This is the first sentence of a paragraph as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. This is the first sentence of a new paragraph as it is preceded by a blank line. This is the second sentence of that paragraph, which is followed by a blank line. ] --- ## Content — Markdown Syntax — Headers The number sign .yellow-h[#] introduces headers; lower levels are created with additional signs — up to total five levels .pull-left[ .inline-c[# Introduction] becomes .out-t[ # Introduction ] .inline-c[## 1. Introduction] becomes .out-t[ ## 1. Introduction ] ] .pull-right[ .inline-c[### 3.1 Introduction] becomes .out-t[ ### 3.1 Introduction ] .inline-c[#### Introduction] becomes .out-t[ #### Introduction ] .inline-c[##### Introduction] becomes .out-t[ ##### Introduction ] ] --- ## Content — Markdown Syntax — Emphases A pair of single asterisk .yellow-h[*] or underscore .yellow-h[_] introduces italics <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">*italics*</span> becomes .out-t[*italics*] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">_italics_</span> becomes .out-t[*italics*] as well <br> A pair of double asterisks or underscores introduces bold <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">**bold**</span> becomes .out-t[**bold**] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">__bold__</span> becomes .out-t[**bold**] as well <br> These two rules can be combined <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">**_bolditalics_**</span> becomes .out-t[**_boldsitalics_**] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">_**bolditalics**_</span> becomes .out-t[_**bolditalics**_] as well --- ## Content — Markdown Syntax — Strikethrough A pair of double tildes .yellow-h[~] introduces strikethrough <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">~~strikethrough~~</span> becomes .out-t[~~strikethrough~~] <br> Strikethrough can be combined with italics or bold <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">**~~strikebold~~**</span> or <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">__~~strikebold~~__</span>, they both become .out-t[**~~strikebold~~**] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">~~**strikebold**~~</span> or <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">~~__strikebold__~~</span>, they both become .out-t[~~**strikebold**~~] as well <br> <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">*~~strikeitalitcs~~*</span> or <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">_~~strikeitalitcs~~_</span>, they both become .out-t[*~~strikeitalitcs~~*] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">~~*strikeitalitcs*~~</span> or <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">~~_strikeitalitcs_~~</span>, they both become .out-t[*~~strikeitalitcs~~*] as well --- ## Content — Markdown Syntax — Links — Internal<sup>*</sup> You can link text to section headers in the same document <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">[Conclusion](#conclusion)</span> becomes .out-t[[Conclusion](#conclusion)], and a click takes the screen to that section <br> Multi-word headers need hyphenation <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">[Literature Review](#literature-review)</span> becomes .out-t[[Literature Review](#literature-review)], and it works only if the second part is hyphenated .footnote[ [*] We will cover links to references, figures, and tables later on. ] --- ## Content — Markdown Syntax — Links — External You can link text to URLs <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">[click here](https://janejdoe.netlify.app/)</span> becomes .out-t[[click here](https://janejdoe.netlify.app/)] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><https://janejdoe.netlify.app></span> becomes .out-t[<https://janejdoe.netlify.app>] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">[https://janejdoe.netlify.app](https://janejdoe.netlify.app/)</span> becomes .out-t[[https://janejdoe.netlify.app](https://janejdoe.netlify.app/)] as well -- <br> You can also link text to email addresses <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;">[email me](mailto:j.j.doe@kriens.edu)</span><sup>*</sup> becomes .out-t[[email me](mailto:j.j.doe@kriens.edu)] <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><j.j.doe@kriens.edu></span> becomes .out-t[<j.j.doe@kriens.edu>] .footnote[ [*] Notice the prefix .yellow-h[mailto:] in the second part of the construct ] --- ## Content — Markdown Syntax — Footnotes Use the .inline-c[[^identifier]] syntax, with identifiers defined elsewhere in the same document, to create a footnote ```r Dr Doe holds a PhD in rock science.[^1] [^1]: She defended her thesis in 2017. ``` .out-t[Dr Doe holds a PhD in rock science.<sup>1</sup>] <br> .footnote[ .out-t[[1] She defended her thesis in 2017.] ] --- ## Content — Markdown Syntax — Lists Lines starting with asterisk .yellow-h[*] as well as plus .yellow-h[+] or minus .yellow-h[−] signs introduce lists ```r - books - articles - reports ``` .out-t[ - books - articles - reports ] --- ## Content — Markdown Syntax — Lists — Nesting Lists can be nested within each other, with indentation ```r + books + articles - published - under review + revised and resubmitted - work in progress ``` .out-t[ + books + articles - published - under review + revised and resubmitted - work in progress ] --- ## Content — Markdown Syntax — Lists — Numbering List items can be numbered ```r 1. books 2. articles - published - under review + revised and resubmitted - work in progress ``` .out-t[ 1. books 2. articles - published - under review + revised and resubmitted - work in progress ] --- ## Content — Markdown Syntax — Lists — Numbering List items can be numbered ```r 1. books 2. articles - published - under review + revised and resubmitted - work in progress ``` .out-t[ 1. books 2. articles - published - under review + revised and resubmitted - work in progress ] --- name: task-lists ## Content — Markdown Syntax — Lists — Tasks Lists Task lists can be created .yellow-h[in plain Markdown, but not in R Markdown] ```r - [x] books - [ ] articles - [ ] published - [x] under review + [x] revised and resubmitted - [ ] work in progress ``` --- ## Content — Markdown Syntax — Dashes Two hyphens grouped together introduce an en-dash .inline-c[‐‐] becomes .out-t[–] <br> Three hyphens grouped together introduce an em-dash .inline-c[‐‐‐] becomes .out-t[—] --- ## Content — Markdown Syntax — Highlithing Highlight any piece of text, by putting it in between a pair of backticks <span style="background-color: #ffff88; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><code>`</code></span> <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><code>`code`</code></span> becomes .inline-c[code] -- <br> Highlight blocks of text by putting them in between two lines, each starting with three backticks <span style="background-color: #ffff88; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><code>```</code></span> ````md ``` df <- mtcars %>% filter(gear > 3) ``` ```` becomes ```r df <- mtcars %>% filter(gear > 3) ``` --- ## Content — Markdown Syntax — Tables The following syntax introduces hand-made tables .pull-left[ <br> ```r |First Column | Second Column | |------------ | ------------- | |First cell | First cell | |Second cell | Second cell | |Third cell | Third cell | ``` ] .pull-right[ <br> | First Column | Second Column | |:------------- |:--------------| | First cell | First cell | | Second cell | Second cell | | Third cell | Third cell | ] -- <br> Note that - .yellow-h[R] Markdown makes it possible to customise hand-made tables futher - we will cover these in [Part 8](#rmd-tables) --- ## Content — Markdown Syntax — Images The syntax <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"></span> embeds images into HTML outputs - similar to the link syntax, only this time it is preceded by an exclamation mark .yellow-h[!] - goes a new line, separate from the text - assumes the figure is in the same folder with the Markdown file<sup>*</sup> .footnote[ [*] If the image is in `static/`, use a path relative to that directory, e.g., <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"></span> ] --- ## Content — Images — Markdown Syntax ```r  ``` <img src="rbd_workshop_files/images_data/boards.jpg" width="40%" style="display: block; margin: auto;" /> --- ## Content — Images — Notes - Images can also be added through YAML - e.g., to blogposts, publications - using the `image` key <br> - These images must be saved in the same directory - as `featured.jpg` - rename or remove it if having them is not desireble - removing the `image` key in YAML is not effective --- class: action ## Exercises — Content - Edit one or more Markdown files in your website project - observe the change locally, in Viewer - stage, commit, push - observe the change online, in a browser <br> - Hint, if you are re-creating [JJD's website](https://janejdoe.netlify.app/): - add and/or edit one or more of the following files - `/content/home/hero.md`, matching [this widget](https://janejdoe.netlify.app/#hero) - `/content/author/admin/index.md`, matching [this widget](https://janejdoe.netlify.app/#about) - `/content/blog/academic-websites/index.md`, matching [this post](https://janejdoe.netlify.app/blog/academic-websites/) - by copy the text from the website to save time - paste into Markdown, and add the syntax <div class="countdown" id="timer_60b87919" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">30</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- name: part8 class: inverse, center, middle # Part 8. R Markdown .footnote[ [Back to the contents slide](#contents-slide). ] --- ## R Markdown — Overview - R Markdown is a special type of Markdown - can run code, and embed the results from data into HTML - have the `.Rmd` or `.Rmarkdown` extension -- <br> - `Hugo` cannot transform R Markdown into HTML - that is why we need the `blogdown` package - transformation of these files takes places locally on your computer - not remotely at the server — e.g., Netlify -- <br> - R Markdown is very similar to Markdown in terms of syntax - except that it includes code - mostly R code, but could also be python --- ## R Markdown — Code — Overview Most codes go inside code chunks - e.g., code that imports and cleans data, and/or produces tables and/or figures ````md ```{r} df <- mtcars %>% mutate(disp_litre = disp / 61.0237) ``` ```` Codes can also go in line with text - .e.g., code that result in a single statistic ```r The average engine displacement of the cars in the dataset is \`r mean(df$disp_litre)` litres. ``` --- ## R Markdown — Code Chunks — Overview - Code chunks are delimited spaces between a pair of three backticks - below is an empty chunk for R code ````md ```{r} ``` ```` -- - `r` is an option of the chunk, indicating that the code in the chunk above should be run by R - it could have been `python`, which we will not cover in this workshop - options go in a pair of curly brackets, on the same line with the first delimiter -- - Chunks can be placed anywhere in .Rmd documents - their output will be placed instead of, or following,<sup>*</sup> the code chunk on the website page .footnote[ [*] Depending on whether code chunks are displayed or not. See the `echo` option in the following slides. ] --- ## R Markdown — Code Chunks — Labels Label the code chunks right after r ````md ```{r, `tidydata`} df <- mtcars %>% mutate(disp_litre = disp / 61.0237) ``` ```` -- <br> Note that - labels are optional, but recommended because they - can be used in text, to refer to tables or figures that code chunks produce - can help with navigating through error messages <br> - duplicate labels lead to an error --- ## R Markdown — Code Chunks — Options - Code chunks take options, listed on the same line with the first delimiter, in curly brackets - avoid spaces around the equal sign <span style="background-color: #ffff88;">=</span> between option tags and values - such spaces might lead to errors <br> - in the example below, the chunk is labelled as `setup`, and and the `include` option is set to `FALSE` - with this option and value, nothing from this chunk will be included in the output document ````md ```{r, tidydata, `include=FALSE`} ``` ```` <br> - The list of options is available at <https://yihui.org/knitr/options> - [R Markdown Cheat Sheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf) provides a helpful list as well --- ## R Markdown — Code Chunks — Options — Defaults Options have default values - e.g., for `echo`, the default is `TRUE` - `echo`: should the source code printed in the output? — yes <br> - therefore the following two chunks have the same function ````md ```{r, tidydata} ``` ```` ````md ```{r, tidydata, `echo=TRUE`} ``` ```` --- ## R Markdown — Code Chunks — Options — Defaults This chunk prints two things in the output document — (a) the code and (b) the head of the data frame ````md ```{r, headdata} head(df) ``` ```` .out-t[ `head(df)` ] <hr style="height:10px; visibility:hidden;" /> .out-t[ ``` ## mpg cyl disp hp drat wt qsec vs am gear carb disp_litre ## Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 2.621932 ## Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 2.621932 ## Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 1.769804 ## Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 4.227866 ## Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 5.899347 ## Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1 3.687092 ``` ] --- ## R Markdown — Code Chunks — Options Setting .inline-c[echo=FALSE] prevents the code from being displayed in the output document ````md ```{r, headdata, `echo=FALSE`} head(df) ``` ```` This chunk therefore prints one thing in the output document — the head of the data frame .out-t[ ``` ## mpg cyl disp hp drat wt qsec vs am gear carb disp_litre ## Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 2.621932 ## Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 2.621932 ## Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 1.769804 ## Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 4.227866 ## Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 5.899347 ## Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1 3.687092 ``` ] --- ## R Markdown — Code Chunks — Other Useful Options Prevent the result(s) of the source code from being displayed in the output document ````md ```{r, headdata, `results="hide"`} head(df) ``` ```` This chunk therefore prints one thing in the output document — the source code .out-t[ `head(df)` ] --- ## R Markdown — Code Chunks — Other Useful Options Cache results for future compilations ````md ```{r ... `cache=TRUE`} ``` ```` -- Prevent R from running the code in the chunk altogether ````md ```{r ... `eval=FALSE`} ``` ```` -- Prevent messages and/or warnings from being displayed in the output ````md ```{r ... `error=FALSE`, `message=FALSE`, `warning=FALSE`} ``` ```` --- ## R Markdown — Code Chunks — Other Useful Options Define the .yellow-h[actual] dimensions of figures, in inches ````md ```{r ... `fig.height=6`, `fig.width=9`} ``` ```` -- Define the size of figures .yellow-h[in the output document], with `out.width` and/or `out.height` ````md ```{r ... `out.width="50%"`} ``` ```` -- Define the alignment of figures — `left`, `right`, or `center` ````md ```{r ... `fig.align="center"`} ``` ```` --- ## R Markdown — Code Chunks — Other Useful Options Define captions for figures ````md ```{r ... `fig.caption="A Scatter Plot"`} ``` ```` -- Set the resolution for figures ````md ```{r ... `dpi=300`} ``` ```` -- Set extra options, which `rmarkdown` will write into the `<img />` tag ````md ```{r ... `out.extra='style="display:block;"'`} ``` ```` --- ## R Markdown — Code Chunks — The Setup Chunk It is recommended to use the first code chunk for general setup, where you can - define .yellow-h[your own defaults] for chunk options, with `knitr::opts_chunk$set()` - avoids repeating chunk options <br> - load the necessary packages <br> - import raw data ````md ```{r, setup, include=FALSE} # `chunk option defaults` knitr::opts_chunk$set(echo=FALSE, message=FALSE) # `packages` library(dplyr) library(ggplot2) library(knitr) # `data` df_raw <- mtcars ``` ```` --- ## R Markdown — Code Chunks — The Setup Chunk — Data Note that the data source can be anywhere that R can access ````md ```{r, setup, include=FALSE} ... # this dataset is `available online` df_online <- read.csv("http://www.parlgov.org/static/data/development-cp1252/view_party.csv") # this dataset is `in the same directory as my .Rmd file` df_local <- read.csv("view_cabinet.csv") ``` ```` --- ## R Markdown — Code Chunks — The Data Chunk I recommend using the second chunk for the main operations<sup>*</sup> on raw data - e.g., for data cleaning and other transformations - some minor transformations could be left to lower chunks - e.g., capitalizing variable names for figures ````md ```{r, data, echo=FALSE ...} df <- df_raw `%>%` `mutate(disp_litre = disp / 61.0237)` ``` ```` --- ## R Markdown — Inline Code — Overview Code can also be incorporated in text, with the <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><code>`r `</code></span> syntax - unlike chunks, these do not take options <br> - the output document will display the result of the code - in the exact place of the source code <br> - the result of the code will have the same formatting with the text --- ## R Markdown — Inline Code — Examples ```r If we multiply _pi_ by 5, we get \`r pi * 5`. ``` .out-t[If we multiply _pi_ by 5, we get 15.7079633.] <hr style="height:10px; visibility:hidden;" /> ```r The average the engine displacement of the cars in the dataset is \`r mean(df$disp_litre)` litres, which would round to \`r round(mean(df$disp_litre), digits = 1)`. ``` .out-t[The average the engine displacement of the cars in the dataset is 3.7808569, which would round to 3.8.] <hr style="height:10px; visibility:hidden;" /> ```r __Only \`r nrow(subset(df, gear == 5))` cars__ in the dataset have five forward gears. ``` .out-t[__Only 5 cars__ in the dataset have five forward gears.] --- ## R Markdown — Figures Place code that produces figures in code chunks .pull-left-c[ ````md ```{r, scatterplot, fig.cap = "A scatterplot of cars.", echo=FALSE} ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) + geom_point() + scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7", breaks = c(4, 6, 8)) + labs(x = "Weight", y = "Miles/Gallon") + theme_bw() ``` ```` ] .pull-right-c[ <!-- --> Figure 1. A scatterplot of cars. ] --- name: cr-figure ## R Markdown — Figures — Cross-References Use the following syntax to refer to figures .pull-left-c[ ```r See Figure `\@ref`(`fig`:`scatterplot`) below. ``` ````md ```{r, `scatterplot`, fig.cap = "A scatterplot of cars.", echo=FALSE} ggplot(data = df, mapping = aes(x = wt, y = mpg, color = cyl)) + geom_point() + scale_colour_gradient(name = "Cylinders", high = "#132B43", low = "#56B1F7", breaks = c(4, 6, 8)) + labs(x = "Weight", y = "Miles/Gallon") + theme_bw() ``` ```` ] .pull-right-c[ .out-t[See Figure [1](#cr-figure) below.] <!-- --> Figure 1. A scatterplot of cars. ] --- ## R Markdown — Tables — Place code that produces .yellow-h[HTML] tables in code chunks ````md ```{r, headdata, echo=FALSE} kable(head(df, 3), caption = "First three rows in the dataset") ``` ```` <br> | | mpg| cyl| disp| hp| drat| wt| qsec| vs| am| gear| carb| disp_litre| |:-------------|----:|---:|----:|---:|----:|-----:|-----:|--:|--:|----:|----:|----------:| |Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620| 16.46| 0| 1| 4| 4| 2.621932| |Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875| 17.02| 0| 1| 4| 4| 2.621932| |Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320| 18.61| 1| 1| 4| 1| 1.769804| Table 1. First three rows in the dataset. --- name: cr-table ## R Markdown — Tables — Cross-References Use the following syntax to refer to tables ```r See Table \@ref(`tab`:`headdata`) below. ``` ````md ```{r, `headdata`, echo=FALSE} kable(head(df, 3), caption = "First three rows in the dataset") ``` ```` <br> .out-t[See Table [1](#cr-table) below.] | | mpg| cyl| disp| hp| drat| wt| qsec| vs| am| gear| carb| disp_litre| |:-------------|----:|---:|----:|---:|----:|-----:|-----:|--:|--:|----:|----:|----------:| |Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620| 16.46| 0| 1| 4| 4| 2.621932| |Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875| 17.02| 0| 1| 4| 4| 2.621932| |Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320| 18.61| 1| 1| 4| 1| 1.769804| Table 1. First three rows in the dataset. --- name: rmd-tables ## R Markdown — Tables — Hand-Made The following syntax, outside code chunks, introduces tables<sup>*</sup> .pull-left[ <br> ```r First Column Second Column ------------ ------------- First cell First cell Second cell Second cell Third cell Third cell ``` ] .pull-right[ <br> | First Column | Second Column | |:------------- |:--------------| | First cell | First cell | | Second cell | Second cell | | Third cell | Third cell | ] .footnote[ <sup>*</sup> The table syntax on this and following seven slides will work in R Markdown files only — they will not work in plain Markdown. ] --- ## R Markdown — Tables — Hand-Made The position of headers, relative to their line underneath, defines column alignments .pull-left[ <br> ```r Left-Aligned Centered ---------------- ---------------- First cell First cell Second cell Second cell Third cell Third cell ``` ] .pull-right[ <br> | Left-Aligned | Centered | |:------------------------------------- | :-----------------------------------: | | First cell | First cell | | Second cell| Second cell | | Third cell | Third cell | ] --- ## R Markdown — Tables — Hand-Made A line starting with a colon, placed before or after tables, introduces captions <br> .pull-left[ ```r Centered Right-Aligned ---------------- ---------------- First cell First cell Second cell Second cell Third cell Third cell *: A hand-made table with R Markdown ``` ] .pull-right[ <center>Table 1: A hand-made table with R Markdown</center> <br> | Centered | Right-Aligned | |:----------------------------------------------: | --------------------------------------------------: | | First cell | First cell | | Second cell| Second cell | | Third cell | Third cell | ] --- ## R Markdown — Tables — Hand-Made The caption line itself needs to be surrounded by empty lines <br> .pull-left[ ```r Centered Right-Aligned ---------------- ---------------- First cell First cell Second cell Second cell Third cell Third cell * : A hand-made table with R Markdown * ``` ] .pull-right[ <center>Table 1: A hand-made table with R Markdown</center> <br> | Centered | Right-Aligned | |:----------------------------------------------: | --------------------------------------------------: | | First cell | First cell | | Second cell| Second cell | | Third cell | Third cell | ] --- ## R Markdown — Tables — Hand-Made Tables are numbered automatically <br> .pull-left[ ```r : A hand-made table with R Markdown Centered Right-Aligned ---------------- ---------------- First cell First cell Second cell Second cell Third cell Third cell ``` ] .pull-right[ <center>.yellow-h[Table 1]: A hand-made table with R Markdown</center> <br> | Centered | Right-Aligned | |:----------------------------------------------: | --------------------------------------------------: | | First cell | First cell | | Second cell| Second cell | | Third cell | Third cell | ] --- ## R Markdown — Tables — Hand-Made Grid tables, with the following syntax, can handle complex cells with multiple lines and/or lists .pull-left[ ```r +--------------------+--------------------+ | First Column | Second Column | +====================+====================+ | - First item | First cell | | - Second item | | | - Third item | | +--------------------+--------------------+ |Second cell | Second cell with a | | | long text | +--------------------+--------------------+ | Third cell | Third cell | | | | +--------------------+--------------------+ : A grid table with multi-line cells ``` ] .pull-right[ <br> <center>Table 1: A grid table with multi-line cells</center> <br> | First Column | Second Column | |:------------------------------------------ |:--------------------------------------------------| | - First item <br> - Second item <br> - Third item | First cell | | Second cell | Second cell with a long<br>text | | Third cell | Third cell | ] --- ## R Markdown — Tables — Hand-Made Grid tables can be aligned as well, with colons at the boundaries of the header separator<sup>*</sup> .pull-left[ ```r +--------------------+--------------------+ | Left-Aligned | Centered | *+:===================+:==================:+ | - First item | First cell | | - Second item | | | - Third item | | +--------------------+--------------------+ |Second cell | Second cell with a | | | long text | +--------------------+--------------------+ | Third cell | Third cell | | | | +--------------------+--------------------+ : A grid table with multi-line cells ``` ] .pull-right[ <br> <center>Table 1: A grid table with multi-line cells</center> <br> | Left-Aligned | Centered | |:--------------------------------------|:---------------------------------:| | - First item <br> - Second item <br> - Third item | First cell | | Second cell | Second cell with a<br>long text | | Third cell | Third cell | ] .footnote[ <sup>*</sup> Use .yellow-h[:=] for left-aligned, .yellow-h[:=:] for centered, .yellow-h[=:] for right-aligned columns. ] --- name: hm-table ## R Markdown — Tables — Hand-Made — Cross-References Use the following syntax to refer to hand-made tables .pull-left[ ```r See Table \@ref(`tab`:`handmade`) below. ``` ```r Centered Right-Aligned ---------------- ---------------- First cell First cell Second cell Second cell Third cell Third cell : `(\#tab:handmade)` A hand-made table with R Markdown ``` ] .pull-right[ .out-t[See Table [1](#mh-table) below.] <br> | Centered | Right-Aligned | |:----------------------------------------------: | --------------------------------------------------: | | First cell | First cell | | Second cell| Second cell | | Third cell | Third cell | <br> <center>Table 1: A hand-made table with R Markdown</center> ] --- class: action ## Exercises — R Markdown - Add and/or edit one or more R Markdown files in your website project - observe the change locally, in Viewer - stage, commit, push - observe the change online, in a browser <br> - Hint, if you are re-creating [JJD's website](https://janejdoe.netlify.app/): - add and edit the following file - `/content/post/cabinet-size/index.Rmd`, matching [this blogpost](https://janejdoe.netlify.app/post/cabinet-size/) - by copy the text from the website to save time - paste into R Markdown, and add the code and syntax <div class="countdown" id="timer_60b87b00" style="top:0;right:0;" data-warnwhen="0"> <code class="countdown-time"><span class="countdown-digits minutes">30</span><span class="countdown-digits colon">:</span><span class="countdown-digits seconds">00</span></code> </div> --- name: references class: inverse, center, middle # References .footnote[ [Back to the contents slide](#contents-slide). ] --- ## References Dowle, M. and Srinivasan, A. (2021). [data.table: Extension of 'data.frame'](https://cran.r-project.org/web/packages/data.table/index.html). R package, version 1.14.0. Sievert, C., Parmer, C., Hocking, T., Chamberlain, S., Ram, K., Corvellec, M., & Despouy, P. (2021). [plotly: Create Interactive Web Graphics via 'plotly.js'](https://cran.r-project.org/web/packages/plotly/index.html). R package, version 4.9.3. Wickham, H. and Grolemund, G. (2019). R for data science. O'Reilly. Open access at [https://r4ds.had.co.nz](https://r4ds.had.co.nz/). Wickham, H., Chang, W., Henry, L., Pedersen, T. L., Takahashi, K., Wilke, C., Woo, K., Yutani, H. and Dunnington, D. (2021). [dplyr: A grammar of data manipulation](https://cran.r-project.org/web/packages/dplyr/index.html). R package, version 1.0.5. Wickham, H., François, W., Henry L. and Müller, K. (2020). [ggplot2: Create elegant data visualisations using the grammar of graphics](https://cran.r-project.org/web/packages/ggplot2/index.html). R package, version 3.3.3. Xie, Y. (2021). [knitr: A general-purpose package for dynamic report generation in R](https://cran.r-project.org/web/packages/knitr/index.html). R package, version 1.33. Xie, Y., Dervieux, C., and Hill, A. P. (2021a). [blogdown: Create blogs and websites with R Markdown](https://cran.r-project.org/web/packages/blogdown/index.html). R package, version 1.3. Xie, Y., Thomas, A., and Hill, A. P. (2021b). blogdown: Creating Websites with R Markdown. Open access at [https://bookdown.org/yihui/blogdown](https://bookdown.org/yihui/blogdown/). --- class: middle, center ## The workshop ends here. ## Congratulations for making it this far, and ## thank you for joining me! .footnote[ [Back to the contents slide](#contents-slide). ]