add citations screenshots

transition-from-rmarkdown.qmd

@@ -4,7 +4,7 @@ title: Transition from RMarkdown
 
 You may already have workflows in RMarkdown and are interested in transitioning to Quarto. There's no hurry to migrate to Quarto. Keep using Rmarkdown and when you're ready the migration will be fine.
 
-Here are some notes as we migrate RMarkdown sites and books. 
+Here are some notes as we migrate RMarkdown sites and books.
 
 *TODO: translating R code chunks*
 
@@ -16,91 +16,91 @@ We got some practice converting from Bookdown to Quarto by helping Gavin Fay con
 
 Our best first reference material for this was Nick Tierney's [Notes on Changing from Rmarkdown/Bookdown to Quarto](https://www.njtierney.com/post/2022/04/11/rmd-to-qmd/). Nick shares some scripts in that post to automate some changes. In our case, the book was small enough that we made all changes manually. [Quarto documentation](https://quarto.org/) was indispensible.
 
-
 ### Experimenting in a low-risk environment
 
-We forked a copy of the Faylab Lab manual to the Openscapes organization, and worked in a branch so we could make changes relatively risk-free. We could always fork a new copy of the original if we "broke" something. (Caution: the default when making a pull request from a fork is to push changes to the original upstream repo, not your fork and it does this without warning if you have write-access to that repo.) With local previews it's easy to test / play with settings to see what they do. We tended to make a change, Preview, then compare the look and functionality of the book to the original. It was helpful to comment out some elements of the configuration file `_output.yml` after their counterparts had been added to the Quarto configuration file `_quarto.yml`, or to confirm they were no longer needed, before making the drastic move of deleting them. 
+We forked a copy of the Faylab Lab manual to the Openscapes organization, and worked in a branch so we could make changes relatively risk-free. We could always fork a new copy of the original if we "broke" something. (Caution: the default when making a pull request from a fork is to push changes to the original upstream repo, not your fork and it does this without warning if you have write-access to that repo.) With local previews it's easy to test / play with settings to see what they do. We tended to make a change, Preview, then compare the look and functionality of the book to the original. It was helpful to comment out some elements of the configuration file `_output.yml` after their counterparts had been added to the Quarto configuration file `_quarto.yml`, or to confirm they were no longer needed, before making the drastic move of deleting them.
 
 ### The conversion
 
 Here are the main steps to convert the Faylab Lab manual from Bookdown to Quarto.
 
-Change all filename extensions `.Rmd` -> `.qmd` (you could Preview after this change and see that the book looks the same).
+Change all filename extensions `.Rmd` -\> `.qmd` (you could Preview after this change and see that the book looks the same).
 
 Create new empty file called `_quarto.yml` and add book metadata there. Here's what ours looked like when we finished the steps below: [`_quarto.yml`](https://github.com/thefaylab/lab-manual/blob/main/_quarto.yml).
 
 Set project type as `book`.
 
-Move metadata out of `index.qmd` and into `_quarto.yml`. Title, author, and publication date were in `index.qmd` with date set using `date: "Last updated: `r Sys.Date()`"`. Now these are in `_quarto.yml` with date set using `date: last-modified `.
+Move metadata out of `index.qmd` and into `_quarto.yml`. Title, author, and publication date were in `index.qmd` with date set using `date: "Last updated:`r Sys.Date()`"`. Now these are in `_quarto.yml` with date set using `date: last-modified`.
 
 Move chapters listing out of `_bookdown.yml` and into `_quarto.yml`.
 
 Add page footer to `_quarto.yml`.
 
-Change insertion of images from html style to Quarto style. (Note Quarto calls them "figures", not "images".) The following snippet will insert the GitHub octocat logo in a page: 
+Change insertion of images from html style to Quarto style. (Note Quarto calls them "figures", not "images".) The following snippet will insert the GitHub octocat logo in a page:
 
-```{.bash}
+``` bash
 ![](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png){fig-align="left" width="35px"}
 ```
 
-
+```{=html}
 <!---
 This not necessary with current RStudio I think:
 Project options > build tools > project build tools > none
 
 Reload project
 --->
-
+```
 ### Citations
 
-The Faylab Lab Manual cited two papers, presenting us with an opportunity to see how easy it is to add references to a Quarto book. Briefly, in the Visual Editor, Insert > Citation > DOI. Pasting the DOI or its full URL, we can insert the citation. This automatically creates a `references.bib` file and adds the full citations at the bottom of the chapter page. In July 2022, we had to manually add a `## References` heading, but this may not be necessary in future Quarto updates. 
-
-TODO screenshot insert citation > DOI in Visual Editor
+The Faylab Lab Manual cited two papers, presenting us with an opportunity to see how easy it is to add references to a Quarto book. Briefly, in the Visual Editor, Insert \> Citation \> DOI. Pasting the DOI or its full URL, we can insert the citation. This automatically creates a `references.bib` file and adds the full citations at the bottom of the chapter page. In July 2022, we had to manually add a `## References` heading, but this may not be necessary in future Quarto updates.
 
-TODO screenshot of source and live page 
+::: {layout-ncol=2}
+![Insert citation via its DOI using RStudio Visual Editor](images/rstudio-insert-citation.png){fig-alt="RStudio Visual Editor Insert dropdown menu with Citation highlighted"}
 
+![](images/rstudio-insert-citation-doi.png)
+:::
 
 ### Publishing notes
 
 Don't specify `output-dir` in `_quarto.yml`. The output directory default is `_book/`, which is what we'd like.
 
 If you currently have a `docs/` folder, delete it.
 
-Update [`.gitignore`](https://github.com/thefaylab/lab-manual/blob/main/.gitignore) to ignore `_book/`. At the same time, we have it ignore caches and a .quarto file: 
+Update [`.gitignore`](https://github.com/thefaylab/lab-manual/blob/main/.gitignore) to ignore `_book/`. At the same time, we have it ignore caches and a .quarto file:
 
-```{.bash}
+``` bash
 /.quarto/
 *_cache/
 _book/
 ```
 
 Once all is settled, delete `_output.yml`.
 
-Once the Openscapes fork was fully reviewed, we made a pull request from that to the main branch of the book's repo. Once that was merged, we set up GitHub Actions to render the book.
+Once the Openscapes fork was fully reviewed, we made a pull request from that to the main branch of the book's repo. Once that was merged, we set up GitHub Actions to render the book. (TODO: instructions for GitHub Actions)
 
 ### GitHub Actions
 
 R
 
 ## Distill to quarto
 
-We transitioned our [events site](https://openscapes.org/events) from distill to quarto in May 2022 (github view [before](https://github.com/Openscapes/events/tree/13f95f507629eba5e6ed721d1902258dcbc421e6) and [after](https://github.com/Openscapes/events/tree/237acd5144d810cb5465cc5616ee453f2e261fbc)). We followed excellent notes and examples from [Nick Tierney](https://www.njtierney.com/post/2022/04/11/rmd-to-qmd/) and [Danielle Navarro](https://blog.djnavarro.net/posts/2022-04-20_porting-to-quarto/). 
+We transitioned our [events site](https://openscapes.org/events) from distill to quarto in May 2022 (github view [before](https://github.com/Openscapes/events/tree/13f95f507629eba5e6ed721d1902258dcbc421e6) and [after](https://github.com/Openscapes/events/tree/237acd5144d810cb5465cc5616ee453f2e261fbc)). We followed excellent notes and examples from [Nick Tierney](https://www.njtierney.com/post/2022/04/11/rmd-to-qmd/) and [Danielle Navarro](https://blog.djnavarro.net/posts/2022-04-20_porting-to-quarto/).
 
-After we had changed all the files, the Build tab in the RStudio IDE still showed "Build website" rather then "Render Website" and "Preview Website", and would error when we pushed them (because that button was expecting a distill site, not a quarto site). To fix this, we updated the `.Rproj` file. Clicking on the `.Rproj` file in the RStudio IDE will open a dialog box where you can click things you want (you can also open these in a text editor or from the GitHub website to see the actual text). To fix this situation with the Build tab: Project Options > Build Tools > Project Build Tools > **None**.
+After we had changed all the files, the Build tab in the RStudio IDE still showed "Build website" rather then "Render Website" and "Preview Website", and would error when we pushed them (because that button was expecting a distill site, not a quarto site). To fix this, we updated the `.Rproj` file. Clicking on the `.Rproj` file in the RStudio IDE will open a dialog box where you can click things you want (you can also open these in a text editor or from the GitHub website to see the actual text). To fix this situation with the Build tab: Project Options \> Build Tools \> Project Build Tools \> **None**.
 
 Looking at files [`/posts/_metadata.yml`](https://github.com/Openscapes/events/blob/main/posts/_metadata.yml) and [`_quarto.yml`](https://github.com/Openscapes/events/blob/main/_quarto.yml) helps see where things are defined. For example, to make event post citations appear, we added `citation: true` to [`/posts/_metadata.yml`](https://github.com/Openscapes/events/blob/main/posts/_metadata.yml) and in [`_quarto.yml`](https://github.com/Openscapes/events/blob/main/_quarto.yml) under the `website` key we set `site-url: https://openscapes.github.io/events`. We deleted `footer.html` used with distill because footer is now defined in `quarto.yml`.
 
 ### Publishing notes
 
-> **Background**: Our distill site had been set up to output to a `docs` folder, and had GitHub Settings > Pages set to look there rather `gh-pages` branch. (Julie note: this was a new-to-me capability when we set up the events distill site in Spring 2021 so I had forgotten that was an option). We've inititally kept this same set-up for now with our events page in `_quarto.yml`: [`output-dir: docs`](https://github.com/Openscapes/events/blob/237acd5144d810cb5465cc5616ee453f2e261fbc/_quarto.yml#L3). However, this is sub-optimal; better to not have to commit and push these files but to instead have a GitHub Action generate them upon a commit. So the following is what we did -
+> **Background**: Our distill site had been set up to output to a `docs` folder, and had GitHub Settings \> Pages set to look there rather `gh-pages` branch. (Julie note: this was a new-to-me capability when we set up the events distill site in Spring 2021 so I had forgotten that was an option). We've inititally kept this same set-up for now with our events page in `_quarto.yml`: [`output-dir: docs`](https://github.com/Openscapes/events/blob/237acd5144d810cb5465cc5616ee453f2e261fbc/_quarto.yml#L3). However, this is sub-optimal; better to not have to commit and push these files but to instead have a GitHub Action generate them upon a commit. So the following is what we did -
 
 **Don't specify `output-dir` in `_quarto.yml`**. The output directory default is `_site/`, which is what we'd like.
 
 If you currently have a `docs/` folder (like we did as we were experimenting), delete it.
 
-**Update `.gitignore` to ignore `_site/`**. At the same time, we have it ignore caches and a .quarto file: 
+**Update `.gitignore` to ignore `_site/`**. At the same time, we have it ignore caches and a .quarto file:
 
-```{.bash}
+``` bash
 /.quarto/
 *_cache/
 _site/
@@ -110,7 +110,7 @@ _site/
 
 **On GitHub.com, in your repo, set up GitHub publishing**
 
-Follow instructions from the [explore and setup chapter](https://openscapes.github.io/quarto-website-tutorial/explore.html#set-up-github-publishing). 
+Follow instructions from the [explore and setup chapter](https://openscapes.github.io/quarto-website-tutorial/explore.html#set-up-github-publishing).
 
 ## Troubleshooting