text on Bookdown to Quarto conversion, WIP

transition-from-rmarkdown.qmd

@@ -10,20 +10,47 @@ Here are some notes as we migrate RMarkdown sites and books.
 
 ## Bookdown to Quarto
 
+Converting a Bookdown book to Quarto is slightly more involved than converting a website. A book has chapters whose order must be defined, and likely has citations and cross-refs. Still, conversion is not that hard.
+
 We got some practice converting from Bookdown to Quarto by helping Gavin Fay convert his lab's fantastic onboarding documentation, the [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/). Here's the GitHub view [before](https://github.com/thefaylab/lab-manual/tree/4ebe9614d4fcab9d782073057ef6e56e9213c167) and [after](https://github.com/thefaylab/lab-manual/tree/3ce2418ed7bd65936a130a42a7f975f55fb9b734).
 
 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. 
 
 
-create `_quarto.yml`
+### 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 Bookdown 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's the order in which we (relative Quarto novices) converted the Faylab Lab manual from Bookdown to Quarto.
+
+- Change all filenames: `filename.Rmd` —> `filename.qmd` (you could try Preview and you'll see that the book looks the same after this change)
+- create new file `_quarto.yml`
+- Set project: 
+    type: book
+
+- default output files (e.g. html) go to `_book/` not `_site/`. We use GitHub Actions to render the book so we added `_book/` to `.gitignore` so that html files generated by rendering would not be tracked (for GitHub commits).
+- Delete `_output.yml`
+
 
+<!---
+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 experience how easy it is to add references to a Quarto book. Briefly, in the Visual Editor, Insert > Citation > DOI. Pasting the DOI or 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 (default Chicago-APA style I think). In July 2022, we had to manually add a `## References` heading, but this may not be necessary in future Quarto updates. 
+
+(TODO: add section on citations, with screenshots, to part of this tutorial that's not just about transition to quarto)
+
+
+
 
-Don't need to delete anything immediately, but look at `output.yml`, purge afterbody. 
 
-Bookdown might be most challenging because of citations and cross-refs but still not that hard
 
 ### GitHub Actions