week8.Rmd

---
title: "Week 8: R Markdown and GitHub Pages"
output:
  html_document:
    toc: true
    toc_depth: 3
    include:
      after_body: footer.html
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, error=TRUE)
```

## Roxygen2 and pkgdown

* [Lecture video](https://youtu.be/UYKezKp5dkY)
* [The lecture notes](week7-roxygen.html)

Links to resources for **pkgdown** sites:

* The NOAA branded **pkgdown template** for you to clone ([repo](https://github.com/RWorkflow-Workshop-2021/pkgdown-template), [webpage](https://rworkflow-workshop-2021.github.io/pkgdown-template/))
* [FIT Resources](https://github.com/nmfs-fish-tools/Resources) `LICENSE` file, `Disclaimer.md` and NOAA footer for your packages here.
* [FIT NOAA Themed pkgdown](https://noaa-fisheries-integrated-toolbox.github.io/resources/workshops/NOAA-pkgdown/). The **pkgdown template** repo uses the information from this.
* [FIT Resources blog](https://noaa-fisheries-integrated-toolbox.github.io/resources/) Scroll down the navbar on left to see coding resources.

## Q & A

### Badges

Check out `usethis::use_badges()`. You'll want to make sure your `Readme.md` file has
```
<!-- badges: start -->

<!-- badges: end -->
```
So **usethis** knows where to put the badge code.

### GitHub Pages

With the last 2 **pkgdown** sites that I put up on GitHub Pages, I had some trouble where GitHub was only showing a page made from the Readme file and not the **pkgdown** site even though I had the GitHub Pages settings done correctly. so on my GitHub repository under Settings > GitHub Pages > branch = main and folder = docs.

To solve, I changed branch = None in Settings > GitHub Pages. That turns off GitHub Pages, then I immediately reset branch = main and folder = docs and hit Save. The **pkgdown** site then appeared within 30 seconds or so.

### GitHub Pages

**How do you decide whether to use a GitHub Pages landing page?**

Anything that is for someone other than me has a landing page. This gives someone a readable entry to the repository with instructions for how to use the repository. I always put a link to the landing page in the repo description. Then it appears on the right side of my repo files and is easy to find.

**Examples of simple pages**

Here are some videos showing how to make a few different simple landing pages from your Readme file or from an RMarkdown file in a docs folder.

* [Super simple](https://youtu.be/HIAvNi-4TkU) - just your `Readme.md` file
* [Use a theme](https://youtu.be/gNVcAnds-Ys) - still just your `Readme.md` file but with a GitHub generated "skin". My [MARSS](https://nwfsc-timeseries.github.io/MARSS/) landing page is generated like this.
* [User an RMarkdown file](https://youtu.be/fA5BeCaX1eo) - from `index.Rmd` in a `docs` folder. This allows you to combine text and figures generated from R. Here is a real example from one of my colleagues [ASSESSOR](https://mdscheuerell.github.io/ASSESSOR/). It was generated from a single `index.Rmd` file just like in the video.

Now that you see how landing pages are often generated, if you see a landing page that you like, go to their `Readme.md` file and see how they wrote it or look for a `docs` folder and their `index.Rmd` file.

**Do you use a landing page for a personal-only repo?**

If the repo is just for myself, then I will often only have a Readme file. I write this for my 'future' self to help me quickly get back into the project at a later date. What I have here is really project dependent. Some things I usually have in the Readme for personal repos are

* If it is an R package, the code to install. I just want to copy and paste this. Saves me time later.
* Basic organization of the repo if it is anything unique or bespoke.
* Where I am at in the project and what the status was when I stopped.