From 1930d6161db16f286729d42f973e7ecd8357edbf Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:50:54 -0500 Subject: [PATCH 1/6] Revise common errors section in faqs.Rmd Updated error descriptions and formatting for clarity including checking the GH_PAT if content isn't rendering or updating --- faqs.Rmd | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/faqs.Rmd b/faqs.Rmd index e56411d..187f3bd 100644 --- a/faqs.Rmd +++ b/faqs.Rmd @@ -17,6 +17,15 @@ Search on the OTTR docs for what you are looking for. Note that first few entrie ## Most Common Errors This guide will describe the most common OTTR errors and pitfalls and how to address them. + +### Most Common Errors: Content not rendering or updating as expected. + +* Check that the GitHub repository `GH_PAT` is up to date. (An associated GitHub Actions error that suggests the `GH_PAT` needs to be udpated is an `exit code 128`) +* Check that the config file is up-to-date. It should look like this: https://github.com/ottrproject/OTTR_Template/blob/main/config_automation.yml. +(be careful to keep your selections for the configuration you would like). + +### Most Common Errors: Pull request checks failing + When you open a pull request, you should see a report like this: ![](https://github.com/ottrproject/OTTR_Template/raw/main/resources/screenshots/gha-actions-error.png) @@ -25,7 +34,7 @@ When you see an ❌ , click on the `Details` button to see the error message. We *** -### `file is not in PNG format`: Google Slides permissions fail +#### `file is not in PNG format`: Google Slides permissions fail _Error example:_ ``` @@ -46,7 +55,7 @@ Your Google Slides presentation you have tried to retrieve a slide from with `ot *** -### You observe the code for `include_slide()` or `` rather than the Google Slide image. +#### You observe the code for `include_slide()` or `` rather than the Google Slide image. Check the formatting of the code chunk, particularly paying attention to the `fig.alt` argument. @@ -76,7 +85,7 @@ Note: Single quotation marks surrounding the whole argument with double quotatio *** -### `Process completed with exit code 1.`: Spell check/url check/quiz format fail: +#### `Process completed with exit code 1.`: Spell check/url check/quiz format fail: Underneath a section that says something like: `**Check spelling/url/quiz errors - fail if too many of them**` you may see something like: ``` @@ -97,7 +106,7 @@ Click on the `Download the errors here` to see the list of errors and which file *** -### `CONFLICT (modify/delete)`: Merge conflict fail: +#### `CONFLICT (modify/delete)`: Merge conflict fail: _Error example:_ ``` @@ -113,7 +122,7 @@ This will often happen when render-preview's git handling doesn't know which cha *** -### `Parser error: while parsing a flow sequence`: _bookdown.yml parse error +#### `Parser error: while parsing a flow sequence`: _bookdown.yml parse error If you see an error like this: ``` @@ -139,7 +148,7 @@ rmd_files: ["index.Rmd", ``` Commit the changes to your `_bookdown.yml` and see if the preview GitHub action runs appropriately. -### `404 error`: GitHub Action link to download and preview `.docx` file is returning a 404 error +#### `404 error`: GitHub Action link to download and preview `.docx` file is returning a 404 error If you get a 404 error after clicking the link while attempting to download the `.docx` file from the GitHub Action rendered previews, then add the following code to the end of the `_output.yml` file: @@ -150,7 +159,7 @@ bookdown::word_document2: Commit the changes to your `_output.yml` and see if the preview GitHub action runs appropriately. -### `Error in if (title == x2) return(head) : the condition has length > 1`: Run bookdown render error +#### `Error in if (title == x2) return(head) : the condition has length > 1`: Run bookdown render error If you observe an error like this: @@ -181,8 +190,4 @@ Then look at the `GA_Script.Rhtml` file and remove the following `html` frontmat ``` -## Content not rendering - -Check that the config file is up-to-date. It should look like this: https://github.com/ottrproject/OTTR_Template/blob/main/config_automation.yml. -(be careful to keep your selections for the configuration you would like). From 0ce9a967f59b9495bf8018d878cfb96799dd66e6 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:40:50 -0500 Subject: [PATCH 2/6] Update faqs.Rmd Co-authored-by: Carrie Wright <23014755+carriewright11@users.noreply.github.com> --- faqs.Rmd | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/faqs.Rmd b/faqs.Rmd index 187f3bd..35d9442 100644 --- a/faqs.Rmd +++ b/faqs.Rmd @@ -20,7 +20,9 @@ This guide will describe the most common OTTR errors and pitfalls and how to add ### Most Common Errors: Content not rendering or updating as expected. -* Check that the GitHub repository `GH_PAT` is up to date. (An associated GitHub Actions error that suggests the `GH_PAT` needs to be udpated is an `exit code 128`) +* Check that the GitHub repository `GH_PAT` is up to date. (An associated GitHub Actions error that suggests the `GH_PAT` needs to be updated is an `exit code 128`) + * Use this [cheatsheet on updating your GH_PAT](https://www.ottrproject.org/cheatsheets/ottr_token.html) if you need help. + * Check that the config file is up-to-date. It should look like this: https://github.com/ottrproject/OTTR_Template/blob/main/config_automation.yml. (be careful to keep your selections for the configuration you would like). From e2d31eaeb658a0a96322a54093af1997df6c3d9b Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:43:27 -0500 Subject: [PATCH 3/6] Increase table of contents depth to 4 --- faqs.Rmd | 1 + 1 file changed, 1 insertion(+) diff --git a/faqs.Rmd b/faqs.Rmd index 35d9442..b842457 100644 --- a/faqs.Rmd +++ b/faqs.Rmd @@ -3,6 +3,7 @@ output: html_document: toc: true toc_float: true + toc_depth: 4 --- ## Search on OTTR docs From 6b044f5589dedba4b4b84c0f714c7c044e51c3cb Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:50:25 -0500 Subject: [PATCH 4/6] Update faqs.Rmd --- faqs.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/faqs.Rmd b/faqs.Rmd index b842457..ab51ad8 100644 --- a/faqs.Rmd +++ b/faqs.Rmd @@ -3,7 +3,7 @@ output: html_document: toc: true toc_float: true - toc_depth: 4 + toc_depth: 4 --- ## Search on OTTR docs From bde54764c3c7f79519cdcc424eb44b29d1af449b Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 14:01:07 -0500 Subject: [PATCH 5/6] Refine error messages and section headings in FAQs Updated error descriptions and formatting in the FAQ section. --- faqs.Rmd | 66 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/faqs.Rmd b/faqs.Rmd index ab51ad8..d807531 100644 --- a/faqs.Rmd +++ b/faqs.Rmd @@ -19,7 +19,9 @@ Search on the OTTR docs for what you are looking for. Note that first few entrie This guide will describe the most common OTTR errors and pitfalls and how to address them. -### Most Common Errors: Content not rendering or updating as expected. +### Content not rendering or updating + +This may be a quiet error where the content just doesn't update and you are not warned that there is a problem. * Check that the GitHub repository `GH_PAT` is up to date. (An associated GitHub Actions error that suggests the `GH_PAT` needs to be updated is an `exit code 128`) * Use this [cheatsheet on updating your GH_PAT](https://www.ottrproject.org/cheatsheets/ottr_token.html) if you need help. @@ -27,36 +29,7 @@ This guide will describe the most common OTTR errors and pitfalls and how to add * Check that the config file is up-to-date. It should look like this: https://github.com/ottrproject/OTTR_Template/blob/main/config_automation.yml. (be careful to keep your selections for the configuration you would like). -### Most Common Errors: Pull request checks failing - -When you open a pull request, you should see a report like this: - -![](https://github.com/ottrproject/OTTR_Template/raw/main/resources/screenshots/gha-actions-error.png) - -When you see an ❌ , click on the `Details` button to see the error message. We'll discuss the most common error messages here. - -*** - -#### `file is not in PNG format`: Google Slides permissions fail - -_Error example:_ -``` -Error in png::readPNG(path, native = TRUE, info = TRUE) : - file is not in PNG format -Calls: local ... lapply -> FUN -> raster_dpi_width -> attr -> -Execution halted -Error in Rscript_render(f, render_args, render_meta, add1, add2) : - Failed to compile .Rmd -Calls: local ... -> render_new_session -> Rscript_render -Execution halted -Error: bookdown::render_book() failed to render the output format 'bookdown::gitbook'. -Execution halted -``` -_What does this mean?:_ - -Your Google Slides presentation you have tried to retrieve a slide from with `ottrpal::include_slide()` is not public. Your Google Slide document must be set to `Anyone with a link`. See [this article for more details.](https://support.wix.com/en/article/setting-permissions-for-google-drive-files-and-folders#:~:text=Settings%20Permissions%20for%20a%20Google,edit%20and%20comment%20as%20well.) The renders will fail if this is not set! See the [setting up images and graphics section](https://www.ottrproject.org/writing_content_courses.html#set-up-images) for more details. - -*** +* Your workflow files may be out of date compared to the template and you may need to request a sync by opening an issue in the template repository. #### You observe the code for `include_slide()` or `` rather than the Google Slide image. @@ -86,6 +59,37 @@ Note: Single quotation marks surrounding the whole argument with double quotatio +*** + +### Errors for pull request check failures + +When you open a pull request, you should see a report like this: + +![](https://github.com/ottrproject/OTTR_Template/raw/main/resources/screenshots/gha-actions-error.png) + +When you see an ❌ , click on the `Details` button to see the error message. We'll discuss the most common error messages here. + +*** + +#### `file is not in PNG format`: Google Slides permissions fail + +_Error example:_ +``` +Error in png::readPNG(path, native = TRUE, info = TRUE) : + file is not in PNG format +Calls: local ... lapply -> FUN -> raster_dpi_width -> attr -> +Execution halted +Error in Rscript_render(f, render_args, render_meta, add1, add2) : + Failed to compile .Rmd +Calls: local ... -> render_new_session -> Rscript_render +Execution halted +Error: bookdown::render_book() failed to render the output format 'bookdown::gitbook'. +Execution halted +``` +_What does this mean?:_ + +Your Google Slides presentation you have tried to retrieve a slide from with `ottrpal::include_slide()` is not public. Your Google Slide document must be set to `Anyone with a link`. See [this article for more details.](https://support.wix.com/en/article/setting-permissions-for-google-drive-files-and-folders#:~:text=Settings%20Permissions%20for%20a%20Google,edit%20and%20comment%20as%20well.) The renders will fail if this is not set! See the [setting up images and graphics section](https://www.ottrproject.org/writing_content_courses.html#set-up-images) for more details. + *** #### `Process completed with exit code 1.`: Spell check/url check/quiz format fail: From b9658c722277b2ef65aff25a8a8c9820b9f777a4 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 4 Dec 2025 14:33:59 -0500 Subject: [PATCH 6/6] Add 'GH' in dictionary since check flags GH from GH_PAT --- resources/dictionary.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/resources/dictionary.txt b/resources/dictionary.txt index 39f41bb..afa5300 100644 --- a/resources/dictionary.txt +++ b/resources/dictionary.txt @@ -67,6 +67,7 @@ Favicons GHA github github +GH GHA Github GitKraken