commit in case visual editor messes me up ;-)

transition-from-rmarkdown.qmd

@@ -10,28 +10,38 @@ 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.
+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](https://quarto.org/docs/books/book-crossrefs.html). 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. 
+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 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. 
+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's the order in which we (relative Quarto novices) converted the Faylab Lab manual from Bookdown to Quarto.
+Here are the main steps to convert 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
+Change all filename extensions `.Rmd` -> `.qmd` (you could Preview after this change and see that the book looks the same).
 
-- 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`
+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 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: 
+
+```{.bash}
+![](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png){fig-align="left" width="35px"}
+```
 
 
 <!---
@@ -43,14 +53,30 @@ 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. 
+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: add section on citations, with screenshots, to part of this tutorial that's not just about transition to quarto)
+TODO screenshot insert citation > DOI in Visual Editor
 
+TODO screenshot of source and live page 
 
 
+### 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: 
+
+```{.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.
 
 ### GitHub Actions