From cbeb04c6025c61c057681b21022304eae9ab3861 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 1 Apr 2026 14:42:30 -0400 Subject: [PATCH 01/37] adding file changes without local render --- README.md | 12 +- _quarto.yml | 48 +- choose_template.qmd | 282 ++++++++++++ contact.qmd | 6 +- customize-docker.qmd | 4 + customize-robots.qmd | 4 + customize-style.qmd | 4 + enroll_sync.qmd | 57 +++ examples.qmd | 187 ++++++-- faqs.qmd | 160 +++++-- getting_started.qmd | 434 +++++++++++++++++- index.qmd | 268 ++++++++++- more_features_borrowing.qmd | 4 + more_features_credits.qmd | 4 + more_features_ganalytic.qmd | 167 +++++-- more_features_gdoc.qmd | 4 + more_features_sources.qmd | 4 + next_steps.qmd | 194 +++++++- ottr-fy.qmd | 6 +- resources/dictionary.txt | 13 + resources/ignore-urls.txt | 2 + ...gR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png | Bin 0 -> 17318 bytes .../figure-docx/unnamed-chunk-4-1.png | Bin 0 -> 6630 bytes ...gR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png | Bin 0 -> 17318 bytes .../figure-html/unnamed-chunk-4-1.png | Bin 0 -> 59737 bytes ...hPhjZ7QSPZLe3NkA8M3eo_gc87451c247_0_17.png | Bin 0 -> 26509 bytes .../figure-html/unnamed-chunk-3-1.png | Bin 0 -> 66074 bytes resources/images/GA_Create_Property.png | Bin 35244 -> 211403 bytes resources/images/GA_Property_setup.png | Bin 70592 -> 208105 bytes resources/images/GA_property.png | Bin 67927 -> 271854 bytes resources/images/GA_start.png | Bin 0 -> 93110 bytes resources/images/GA_stream_link_correct.png | Bin 65465 -> 160613 bytes resources/images/GA_web.png | Bin 33411 -> 126647 bytes resources/images/Image_res_72.png | Bin 0 -> 15394 bytes resources/images/basic_otter_circle.PNG | Bin 0 -> 1378500 bytes .../basic_otter_sticker_transparent.PNG | Bin 0 -> 1761329 bytes resources/images/itcr_training_network.png | Bin 0 -> 216608 bytes resources/images/logo.png | Bin 0 -> 30719 bytes resources/images/methods_of_writing.jpg | Bin 0 -> 119259 bytes resources/images/otter.ico | Bin 0 -> 185060 bytes resources/images/pull_request_model.jpg | Bin 0 -> 188629 bytes resources/images/tools.png | Bin 0 -> 148620 bytes resources/screenshots/GA_Create_Property.png | Bin 0 -> 35244 bytes resources/screenshots/GA_ID.png | Bin 0 -> 121523 bytes resources/screenshots/GA_Property_setup.png | Bin 0 -> 70592 bytes resources/screenshots/GA_account.png | Bin 0 -> 137227 bytes resources/screenshots/GA_admin.png | Bin 0 -> 59581 bytes resources/screenshots/GA_check.png | Bin 0 -> 14266 bytes resources/screenshots/GA_property.png | Bin 0 -> 67927 bytes resources/screenshots/GA_reports.png | Bin 0 -> 21814 bytes resources/screenshots/GA_stream_link.png | Bin 0 -> 69188 bytes .../screenshots/GA_stream_link_correct.png | Bin 0 -> 65465 bytes resources/screenshots/GA_terms.png | Bin 0 -> 57127 bytes resources/screenshots/GA_web.png | Bin 0 -> 33411 bytes resources/screenshots/GHASetUp.png | Bin 0 -> 159828 bytes resources/screenshots/OTTR_Robot_Image.png | Bin 0 -> 196614 bytes resources/screenshots/add-jhudsl-robot.png | Bin 0 -> 44759 bytes resources/screenshots/add-repo-sync.png | Bin 0 -> 181663 bytes resources/screenshots/automatic_checks.png | Bin 0 -> 199595 bytes resources/screenshots/branch_settings.png | Bin 0 -> 166566 bytes resources/screenshots/branches.png | Bin 0 -> 134497 bytes resources/screenshots/change_https.png | Bin 0 -> 154423 bytes .../screenshots/change_pages_settings.png | Bin 0 -> 64978 bytes resources/screenshots/check-comments.png | Bin 0 -> 130352 bytes resources/screenshots/check_results.png | Bin 0 -> 124154 bytes resources/screenshots/check_results_pass.png | Bin 0 -> 111219 bytes resources/screenshots/clone.png | Bin 0 -> 27616 bytes .../screenshots/creating_new_course_repo.png | Bin 0 -> 205483 bytes resources/screenshots/edit-sync.yml.png | Bin 0 -> 182475 bytes resources/screenshots/example_credits.png | Bin 0 -> 89260 bytes resources/screenshots/file_pane.png | Bin 0 -> 60868 bytes resources/screenshots/gha-actions-error.png | Bin 0 -> 249077 bytes resources/screenshots/gha-checks.png | Bin 0 -> 130878 bytes resources/screenshots/gha-preview-comment.png | Bin 0 -> 107312 bytes resources/screenshots/git-secrets.png | Bin 0 -> 50934 bytes resources/screenshots/guide_issues.png | Bin 0 -> 209463 bytes resources/screenshots/guides_issues.png | Bin 0 -> 84013 bytes resources/screenshots/guides_issues_2.png | Bin 0 -> 209325 bytes resources/screenshots/guides_issues_3.png | Bin 0 -> 209511 bytes resources/screenshots/guides_issues_4.png | Bin 0 -> 209433 bytes resources/screenshots/issue_enroll.png | Bin 0 -> 78789 bytes resources/screenshots/main.png | Bin 0 -> 17252 bytes resources/screenshots/messages.png | Bin 0 -> 23475 bytes resources/screenshots/new_project.png | Bin 0 -> 45349 bytes resources/screenshots/numbering_bookdown.png | Bin 0 -> 107655 bytes resources/screenshots/numbering_leanpub.png | Bin 0 -> 88778 bytes resources/screenshots/output_file_with_GA.png | Bin 0 -> 104215 bytes resources/screenshots/pages_settings.png | Bin 0 -> 142157 bytes resources/screenshots/pr-prompt.png | Bin 0 -> 230487 bytes resources/screenshots/preview_comment.png | Bin 0 -> 101698 bytes resources/screenshots/project_directory.png | Bin 0 -> 68892 bytes resources/screenshots/project_type.png | Bin 0 -> 47491 bytes resources/screenshots/pull_request.png | Bin 0 -> 79208 bytes resources/screenshots/pull_request_2.png | Bin 0 -> 103434 bytes resources/screenshots/pull_request_3.png | Bin 0 -> 25010 bytes resources/screenshots/question_example.png | Bin 0 -> 50463 bytes resources/screenshots/request-reviewer.png | Bin 0 -> 46623 bytes resources/screenshots/select_directory.png | Bin 0 -> 58626 bytes resources/screenshots/slide_url.png | Bin 0 -> 218423 bytes resources/screenshots/spell_check_comment.png | Bin 0 -> 84058 bytes resources/screenshots/spell_check_fails.png | Bin 0 -> 59605 bytes resources/screenshots/template_button.png | Bin 0 -> 220985 bytes resources/screenshots/templates_to_edit.png | Bin 0 -> 163012 bytes 103 files changed, 1692 insertions(+), 172 deletions(-) create mode 100644 choose_template.qmd create mode 100644 enroll_sync.qmd create mode 100644 resources/images/02-chapter_of_course_files/figure-docx/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png create mode 100644 resources/images/02-chapter_of_course_files/figure-docx/unnamed-chunk-4-1.png create mode 100644 resources/images/02-chapter_of_course_files/figure-html/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png create mode 100644 resources/images/02-chapter_of_course_files/figure-html/unnamed-chunk-4-1.png create mode 100644 resources/images/03-test_cases_files/figure-html/12DPZgPteQBwgal6kSPP58zhPhjZ7QSPZLe3NkA8M3eo_gc87451c247_0_17.png create mode 100644 resources/images/04-figures_files/figure-html/unnamed-chunk-3-1.png create mode 100644 resources/images/GA_start.png create mode 100644 resources/images/Image_res_72.png create mode 100644 resources/images/basic_otter_circle.PNG create mode 100644 resources/images/basic_otter_sticker_transparent.PNG create mode 100644 resources/images/itcr_training_network.png create mode 100644 resources/images/logo.png create mode 100644 resources/images/methods_of_writing.jpg create mode 100644 resources/images/otter.ico create mode 100644 resources/images/pull_request_model.jpg create mode 100644 resources/images/tools.png create mode 100644 resources/screenshots/GA_Create_Property.png create mode 100644 resources/screenshots/GA_ID.png create mode 100644 resources/screenshots/GA_Property_setup.png create mode 100644 resources/screenshots/GA_account.png create mode 100644 resources/screenshots/GA_admin.png create mode 100644 resources/screenshots/GA_check.png create mode 100644 resources/screenshots/GA_property.png create mode 100644 resources/screenshots/GA_reports.png create mode 100644 resources/screenshots/GA_stream_link.png create mode 100644 resources/screenshots/GA_stream_link_correct.png create mode 100644 resources/screenshots/GA_terms.png create mode 100644 resources/screenshots/GA_web.png create mode 100644 resources/screenshots/GHASetUp.png create mode 100644 resources/screenshots/OTTR_Robot_Image.png create mode 100644 resources/screenshots/add-jhudsl-robot.png create mode 100644 resources/screenshots/add-repo-sync.png create mode 100644 resources/screenshots/automatic_checks.png create mode 100644 resources/screenshots/branch_settings.png create mode 100644 resources/screenshots/branches.png create mode 100644 resources/screenshots/change_https.png create mode 100644 resources/screenshots/change_pages_settings.png create mode 100644 resources/screenshots/check-comments.png create mode 100644 resources/screenshots/check_results.png create mode 100644 resources/screenshots/check_results_pass.png create mode 100644 resources/screenshots/clone.png create mode 100644 resources/screenshots/creating_new_course_repo.png create mode 100644 resources/screenshots/edit-sync.yml.png create mode 100644 resources/screenshots/example_credits.png create mode 100644 resources/screenshots/file_pane.png create mode 100644 resources/screenshots/gha-actions-error.png create mode 100644 resources/screenshots/gha-checks.png create mode 100644 resources/screenshots/gha-preview-comment.png create mode 100644 resources/screenshots/git-secrets.png create mode 100644 resources/screenshots/guide_issues.png create mode 100644 resources/screenshots/guides_issues.png create mode 100644 resources/screenshots/guides_issues_2.png create mode 100644 resources/screenshots/guides_issues_3.png create mode 100644 resources/screenshots/guides_issues_4.png create mode 100644 resources/screenshots/issue_enroll.png create mode 100644 resources/screenshots/main.png create mode 100644 resources/screenshots/messages.png create mode 100644 resources/screenshots/new_project.png create mode 100644 resources/screenshots/numbering_bookdown.png create mode 100644 resources/screenshots/numbering_leanpub.png create mode 100644 resources/screenshots/output_file_with_GA.png create mode 100644 resources/screenshots/pages_settings.png create mode 100644 resources/screenshots/pr-prompt.png create mode 100644 resources/screenshots/preview_comment.png create mode 100644 resources/screenshots/project_directory.png create mode 100644 resources/screenshots/project_type.png create mode 100644 resources/screenshots/pull_request.png create mode 100644 resources/screenshots/pull_request_2.png create mode 100644 resources/screenshots/pull_request_3.png create mode 100644 resources/screenshots/question_example.png create mode 100644 resources/screenshots/request-reviewer.png create mode 100644 resources/screenshots/select_directory.png create mode 100644 resources/screenshots/slide_url.png create mode 100644 resources/screenshots/spell_check_comment.png create mode 100644 resources/screenshots/spell_check_fails.png create mode 100644 resources/screenshots/template_button.png create mode 100644 resources/screenshots/templates_to_edit.png diff --git a/README.md b/README.md index 1d6065e..a726319 100644 --- a/README.md +++ b/README.md @@ -1,11 +1 @@ -# OTTR for Websites -- Quarto version! - -Get started by going to [ottrproject.org](https://www.ottrproject.org/getting_started.html)! - -This is a template for creating websites from qmd files hosted on GitHub with three helpful automations following a pull request to the repository: spelling check, broken link check, and website rendering. - -- Check for spelling errors more intensively than RStudio and allow you to add words to the dictionary -- Check for broken links - you will be warned about broken links -- Automatic rendering of the website for previewing before merges -- Automatic rendering of the website upon merging to main -- Docker images that can be customized. +This repository makes the content for the OTTR website: ottrproject.org. It introduces folks to OTTR (open-source tools for Training Resources). diff --git a/_quarto.yml b/_quarto.yml index b266416..c3f3ad5 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -13,34 +13,46 @@ website: menu: - text: "Getting Started" href: getting_started.qmd - - text: "Next Steps" + - text: "Next steps" href: next_steps.qmd - - text: "Customization" + - text: "Example use cases" + href: examples.qmd + - text: "Build with OTTR" menu: - - text: "Customizing checks {{< fa robot title='A robot' >}}" - href: customize-robots.qmd - - text: "Customizing style {{< fa palette title='A palette' >}}" + - text: "Template" + href: getting_started.qmd + - text: "Enroll for sync updates" + href: enroll_sync.qmd + - text: "OTTR-fy existing repo" + href: ottr-fy.qmd + - text: "---" + - text: "Customize" + - text: "Style {{< fa palette title='A palette' >}}" href: customize-style.qmd - - text: "Customizing Docker {{< fa gears title='gears' >}}" + - text: "Checks {{< fa robot title='A robot' >}}" + href: customize-robots.qmd + - text: "Docker {{< fa gears title='gears' >}}" href: customize-docker.qmd + - text: "Advanced Integrations" + menu: + - text: "Google Analytics {{< fa chart-line title='a line chart' >}}" + href: more_features_ganalytic.qmd - text: "Citing sources {{< fa quote-left title='A left quotation mark' >}}" href: more_features_sources.qmd - text: "Giving credits {{< fa award title='An award' >}}" href: more_features_credits.qmd + - text: "Google Docs {{< fa file title='a file folder' >}}" + href: more_features_gdoc.qmd - text: "Borrowing chapters {{< fa bookmark title='A bookmark' >}}" href: more_features_borrowing.qmd - - text: "Compatibility with Google Docs {{< fa file title='a file folder' >}}" - href: more_features_gdoc.qmd - - text: "Google Analytics {{< fa chart-line title='a line chart' >}}" - href: more_features_ganalytic.qmd - - text: "OTTR-fying an existing repository" - href: ottr-fy.qmd - - text: "About OTTR babies" - href: examples.qmd - - text: "Troubleshooting {{< fa tools title='tools' >}}" - href: faqs.qmd - - text: "Contact {{< fa envelope title='An envelope' >}}" - href: contact.qmd + - text: "Help me choose my template" + href: choose_template.qmd + - text: "Help" + menu: + - text: "Troubleshooting {{< fa tools title='tools' >}}" + href: faqs.qmd + - text: "Contact {{< fa envelope title='An envelope' >}}" + href: contact.qmd - text: "{{< fa brands github title='The GitHub logo' >}}" href: https://github.com/ottrproject/OTTR_Template diff --git a/choose_template.qmd b/choose_template.qmd new file mode 100644 index 0000000..257e2dd --- /dev/null +++ b/choose_template.qmd @@ -0,0 +1,282 @@ +--- +title: "Help me choose my template" +--- + +Not sure which OTTR template is right for you? Answer two quick questions and we'll point you to the right setup guide. + + + +
+
+
+
+ + + +--- + +## At a glance + +| Template | Best for | Write in | Can also publish to | +|:---|:---|:---:|:---| +| [Quarto Courses](getting_started.html#quarto-courses) ⭐ | New courses, starting fresh , existing `.qmd` course files | `.qmd` | GitHub Pages · Coursera · Leanpub | +| [R Markdown Courses](getting_started.html#r-markdown-courses) | Existing `.Rmd` course files | `.Rmd` | GitHub Pages · Coursera · Leanpub | +| [Quarto Websites](getting_started.html#quarto-websites) ⭐ | New websites, starting fresh , existing `.qmd` course files| `.qmd` | GitHub Pages | +| [R Markdown Websites](getting_started.html#r-markdown-websites) | Existing `.Rmd` website files | `.Rmd` | GitHub Pages | +| [Dashboards](getting_started.html#dashboards) | Metrics tracking & reporting | `.Rmd` | GitHub Pages | + +## Key questions to ask yourself + +**Courses vs. Websites** + +- Choose a **Course** template if you want a sidebar table of contents, chapter-by-chapter navigation, and the option to publish to Coursera or Leanpub. +- Choose a **Website** template if you want a top navigation bar and a more flexible page structure — like this documentation site. + +**Quarto vs. R Markdown** + +- Choose **Quarto** if you are starting a new project. It is the modern successor to R Markdown, supports R and Python, and is what OTTR recommends for all new content. +- Choose **R Markdown** if you already have a set of `.Rmd` files you want to build on, or if your team is already working in R Markdown and a migration isn't practical right now. + +**Dashboards** + +- Choose the **Dashboard** template if your primary goal is to collect and display metrics — number of GitHub stars, Google Analytics traffic, CRAN downloads, Calendly bookings, and more — powered by the [`metricminer`](https://www.metricminer.org/) R package. + +--- + +[Get Started](getting_started.qmd) → diff --git a/contact.qmd b/contact.qmd index fc4eedc..d0f683c 100644 --- a/contact.qmd +++ b/contact.qmd @@ -4,8 +4,10 @@ output: html_document --- +If you have questions please contact: +- Carrie Wright (cwright2@fredhutch.org) -If you have questions please contact: +--- -* Carrie Wright (cwrigh60@jhu.edu) +← [Troubleshooting](faqs.qmd)   [Home](index.qmd) diff --git a/customize-docker.qmd b/customize-docker.qmd index 5afeff3..43be7ce 100644 --- a/customize-docker.qmd +++ b/customize-docker.qmd @@ -220,3 +220,7 @@ If you do choose to use the action manually, then you can use this by going to ` ![](resources/images/docker-gha.png) For more guidance on how to personalize Docker images, we taking our [Containers for Scientist course](https://hutchdatascience.org/Containers_for_Scientists/). Or file a GitHub issue on the relevant repository. + +--- + +← [Customizing Checks](customize-robots.qmd)   [Next Steps](next_steps.qmd) → diff --git a/customize-robots.qmd b/customize-robots.qmd index 3459e28..c682240 100644 --- a/customize-robots.qmd +++ b/customize-robots.qmd @@ -216,3 +216,7 @@ To investigate why a GitHub action has failed, go to `Actions` and click on the See our [FAQ's section](./faqs.html) for the most commonly encountered errors and how to address them. If you are unsure what the error message means and have trouble addressing it, please [file an issue on the OTTR_Template repository to get help](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=cansavvy&labels=bug&template=course-template-problem-report.md). + +--- + +← [Customizing Style](customize-style.qmd)   [Customizing Docker](customize-docker.qmd) → diff --git a/customize-style.qmd b/customize-style.qmd index 025c7f5..5b249df 100644 --- a/customize-style.qmd +++ b/customize-style.qmd @@ -103,3 +103,7 @@ If you would like to change the current light blue color to be a different color If you would like to change the image at the top of the Bookdown version of the course, you need to do the following steps: * Add a new image file to the `assets` directory * Modify the `assets/big-image.html` file on line 11. Change out `src = "assets/dasl_thin_main_image.png"` so that `dasl_thin_main_image.png` is replaced with the name of your image file. + +--- + +← [Next Steps](next_steps.qmd)   [Customizing Checks](customize-robots.qmd) → diff --git a/enroll_sync.qmd b/enroll_sync.qmd new file mode 100644 index 0000000..c921e4d --- /dev/null +++ b/enroll_sync.qmd @@ -0,0 +1,57 @@ +--- +title: "Enroll for Sync Updates" +--- + +The OTTR templates are always a work in progress. New features are added and bugs are smoothed out over time. [Your feedback is greatly appreciated](https://github.com/ottrproject/OTTR_Template/issues/new/choose). When updates are made to non-content files (checks, automation), pull requests are automatically filed to downstream repositories made from the template. + +## Add `jhudsl-robot` as a collaborator + +*You can skip this step if your course is in the `jhudsl` organization.* + +To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a collaborator with write access: + +1. In your repository, go to **Settings** > **Collaborators & Teams** and click **Add people**. +2. Search for and add `jhudsl-robot`. +3. If prompted, choose the **Write** option, then click **Add jhudsl-robot to this repository**. + + + +## Which sync file should you edit? + +Add your repository name to the `.github/sync.yml` file of the OTTR template you created your repository from: + +- [OTTR_Template sync file](https://github.com/ottrproject/OTTR_Template/blob/main/.github/sync.yml) — for R Markdown courses +- [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites +- [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes + +## If you are part of the jhudsl GitHub organization + +1. Open the relevant sync file above and click the pencil icon to edit. +2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/edit-sync.yml.png) + +3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. +4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. + +## If you are not part of the jhudsl GitHub organization + +Use one of these options: + +- **Google Form** — submit your organization/username and repo name in the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) and we'll make the edit for you. +- **Open an issue** — use the links in the table below and provide your repo info; we'll update `sync.yml` for you. +- **Fork and PR** — fork the template repo, edit `sync.yml` on a new branch adding your repo name where it says `#NEW REPO HERE#`, commit, and open a pull request. Add a comment tagging `@kweav` so we see it. + +| Repository | Issue Links | +|:---:|:---| +| OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | +| OTTR_Quizzes | [Open an issue](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | +| OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) | + +

+_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._ +

+ +--- + +**← Back to:** [Next Steps](next_steps.qmd) · **Continue with:** [Customizing Style](customize-style.qmd)**→** diff --git a/examples.qmd b/examples.qmd index da9e619..42d4afe 100644 --- a/examples.qmd +++ b/examples.qmd @@ -1,55 +1,144 @@ --- title: "Examples of OTTR in the Wild" -output: - html_document +toc: false --- -# OTTR spinoff babies +```{=html} + +``` + +Explore courses, websites, and templates built with OTTR. If you've made something with OTTR and would like it featured here, [let us know](contact.qmd). + +```{=html} +
+ +
+ Course +

DaSEH Instructor Guide

+

A course instructor guide for the Data Science for the Experience of Health (DaSEH) program, built with OTTR.

+
+ View course +
+
+ +
+ Course +

Baltimore Community Course

+

A community-focused data science course built with OTTR for the Baltimore community.

+
+ View course +
+
+ +
+ Template +

AnVIL Template

+

An OTTR-based template for courses built around the AnVIL cloud computing platform.

+
+ View example + GitHub +
+
+ +
+ Template +

DataTrail Template

+

An OTTR-based template for DataTrail courses, with custom branding and structure.

+
+ View example + GitHub +
+
+ +
+ Template +

OTTR Quarto

+

The Quarto-based OTTR template for building courses and websites using .qmd files. Recommended for all new projects.

+
+ GitHub +
+
+ +
+ Dashboard +

Metricminer Dashboard

+

A dashboard template powered by the metricminer R package. Tracks GitHub, Google Analytics, Google Forms, CRAN, Calendly, and more.

+
+ GitHub + metricminer.org +
+
+ +
+``` -We are actively working on developing additional versions of our original template to cater to specific needs. These variations can range from technical modifications that simplify the template, to tangential adaptations, or even more complex versions compared to the original OTTR template. - -We also noticed that if specific branding or variations of the original template need to be used many times, it's often easier to create a new template. - -We affectionately call these spinoff templates OTTR "babies". - -If you find yourself making a full set of courses and multiple repositories from OTTR, you may want to make a template from our template (If you need to go this route, we recommend reaching out to the OTTR maintainers by filing a GitHub issue and assigning `@cansavvy` and `@carriewright11`). Also please reach out if you have any other interesting ideas or suggestions! - -## Quarto spinoff - -Maybe you prefer a Quarto website! We have that: https://github.com/ottrproject/OTTR_Quarto - -## Jekyll spinoff - -TBD: Coming soon - -## metric collection - -This is a template powered by the `metricminer` R package to allow you to display metrics in a dashboard. -This template shows basics for how you can display metrics collected from: -[Github template repo](https://github.com/ottrproject/metricminer-dashboard/tree/main) - -- Google Analytics -- Google Forms -- GitHub -- CRAN -- Calendly - -And more websites being added. [See metricminer.org for more details!](https://www.metricminer.org/) - -## AnVIL template - -This is a template (made from our main OTTR Template) that is used for a set of courses being made for the [AnVIL set of cloud tools](https://anvilproject.org/) - -- [GitHub repository and source code](https://github.com/jhudsl/AnVIL_Template) - -Courses will look similar to this [link](https://jhudatascience.org/AnVIL_Template/). - -## DataTrail template - -This is a template (made from our main OTTR Template) that will be used for a set of courses being made for [DataTrail](https://www.datatrail.org/) - -- [GitHub repository and source code](https://github.com/datatrail-jhu/DataTrail_Template) - -Courses will look similar to this [link](https://datatrail-jhu.github.io/DataTrail_Template/introduction.html). +--- -
+Ready to build your own? [Get Started](getting_started.qmd) → diff --git a/faqs.qmd b/faqs.qmd index d3e4bd3..147dd39 100644 --- a/faqs.qmd +++ b/faqs.qmd @@ -1,28 +1,90 @@ --- -title: Troubleshooting -output: - html_document +format: + html: + toc: true + toc-depth: 4 + toc-float: true + toc-location: left --- - +## Search on OTTR docs + +Search on the OTTR docs for what you are looking for. Note that first few entries are sponsored, the actually helpful stuff will be below that. + +```{=html} + +``` + +::: gcse-searchbox-only +::: ## Most Common Errors This guide will describe the most common OTTR errors and pitfalls and how to address them. + +### 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. + +- 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). + +- 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. + +Check the formatting of the code chunk, particularly paying attention to the `fig.alt` argument. + +Make sure there are: + +- no line breaks +- only **one type** of quotation marks used in `fig.alt` (either all single or all double quotes) + +Examples: + +`fig.alt = "This is an example sentence where I want to bring attention to "this specific phrase" and not the rest of it."` + +or + +`fig.alt = 'This is an example sentence where I want to bring attention to 'this specific phrase' and not the rest of it.'` + +
+ +Click for more information + +Options for correct formatting of quotation marks within the `fig.alt` text argument: + +``` + - Double quotation marks surrounding the whole argument with double quotation marks around any specific phrases within the argument + - Single quotation marks surround the whole argument with single quotation marks around any specific phrases within the argument + - Double quotation marks surrounding the whole argument with single quotation marks around any specific phrases within the argument (this will also work) +``` + +Note: Single quotation marks surrounding the whole argument with double quotation marks around specific phrases within the argument will cause issues that may be not be as obvious at first. It will cause the images to not be properly rendered. + +
+ +------------------------------------------------------------------------ + +### 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 +#### `file is not in PNG format`: Google Slides permissions fail -_Error example:_ -``` +*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 -> @@ -34,16 +96,18 @@ Execution halted Error: bookdown::render_book() failed to render the output format 'bookdown::gitbook'. Execution halted ``` -_What does this mean?:_ + +*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: +#### `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: -``` + +``` Run exit 1 exit 1 shell: sh -e {0} @@ -51,7 +115,8 @@ Error: Process completed with exit code 1. ``` This is failing on purpose -- it means that checker has found errors. Return to your pull request page and look for a comment that says something like: -``` + +``` ⚠️ There are errors that need to be addressed. Read this guide for more info. Download the errors here. Comment updated at with changes from @@ -59,28 +124,30 @@ Comment updated at with changes from Click on the `Download the errors here` to see the list of errors and which files they were found in. For help in addressing these errors, click on the `Read this guide for more info` button. -*** +------------------------------------------------------------------------ -### `CONFLICT (modify/delete)`: Merge conflict fail: +#### `CONFLICT (modify/delete)`: Merge conflict fail: -_Error example:_ -``` +*Error example:* + +``` CONFLICT (modify/delete): deleted in and modified in HEAD. Version HEAD of left in tree. ``` This will often happen when render-preview's git handling doesn't know which changes you are looking to preview. The easiest way to fix this problem is to create a separate pull request that completely deletes the files lists. To do this, follow these steps: -1) Take note of your pull request's number. Go to the pull request page and see what `#number` is posted there. -2) On your GitHub repository, go to `Code` and click on `Branches`. -3) Your pull request's preview is made on a branch named `preview- `. Find this branch and click the trash can icon. This will delete the preview branch and hopefully get rid of this error. [Read this](https://www.git-tower.com/learn/git/faq/github-delete-branch) for more info on how to delete a branch. -4) Re-trigger your GitHub actions run and it should pass. +1) Take note of your pull request's number. Go to the pull request page and see what `#number` is posted there. +2) On your GitHub repository, go to `Code` and click on `Branches`. +3) Your pull request's preview is made on a branch named `preview-`. Find this branch and click the trash can icon. This will delete the preview branch and hopefully get rid of this error. [Read this](https://www.git-tower.com/learn/git/faq/github-delete-branch) for more info on how to delete a branch. +4) Re-trigger your GitHub actions run and it should pass. -*** +------------------------------------------------------------------------ -### `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: -``` + +``` Run Rscript -e "bookdown::render_book('index.Rmd', output_format = 'all')" Error in yaml::yaml.load(..., eval.expr = TRUE) : Parser error: while parsing a flow sequence at line 4, column 12 did not find expected ',' or ']' at line 11, column 13 @@ -91,9 +158,9 @@ Error: Process completed with exit code 1. It means that the formatting in your `_bookdown.yml` is off. If you forget a comma, or quote, or a `]` this message will appear in the github actions preview run. -Take a careful look at the `_bookdown.yml`. Keep in mind that _bookdown.yml rmd_files spec should look like this (indents, quotes, and commas included in this pattern): +Take a careful look at the `_bookdown.yml`. Keep in mind that \_bookdown.yml rmd_files spec should look like this (indents, quotes, and commas included in this pattern): -``` +``` rmd_files: ["index.Rmd", "01-intro.Rmd", "02-chapter_of_course.Rmd", @@ -101,24 +168,25 @@ rmd_files: ["index.Rmd", "About.Rmd", "References.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: -``` +``` bookdown::word_document2: toc: true ``` 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: -``` +``` Error in if (title == x2) return(head) : the condition has length > 1 Calls: ... split_chapters -> build -> sub -> is.factor -> prepend_chapter_title Execution halted @@ -129,7 +197,7 @@ Then look at the `GA_Script.Rhtml` file and remove the following `html` frontmat (at the beginning of the file) -``` +``` @@ -141,7 +209,7 @@ Then look at the `GA_Script.Rhtml` file and remove the following `html` frontmat (at the end of the file) -``` +``` ``` @@ -150,8 +218,32 @@ Then look at the `GA_Script.Rhtml` file and remove the following `html` frontmat 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). +### `could not read Username for 'https://github.com': terminal prompts disabled`: GitHub authentication failure + +_Error example:_ +``` +The process '/usr/bin/git' failed with exit code 128 +could not read Username for 'https://github.com': terminal prompts disabled +could not read Username for 'https://github.com': terminal prompts disabled +could not read Username for 'https://github.com': terminal prompts disabled +``` + +_What does this mean?:_ + +This error occurs when the GitHub Action workflow does not have the necessary permissions to authenticate with GitHub. This is typically caused by missing or insufficient repository permissions for the workflow's `GITHUB_TOKEN`. + +To fix this, see the [OTTR token cheatsheet](https://www.ottrproject.org/cheatsheets/ottr_token.html) for detailed instructions, or follow these steps: + +1) Go to your repository's **Settings** > **Actions** > **General**. +2) Under **Workflow permissions**, select `Read and write permissions`. +3) Click **Save**, then re-run the failed workflow. + ## Contact Info If you have a question that's not addressed by this website or just wanna chat with us about something else, please email us at itcrtrainingnetwork@gmail.com OR you can [leave a GitHub issue here](https://github.com/ottrproject/OTTR_Template/issues/new) and assign or "at" a team member in the description/a comment (`@carriewright11`, `@kweav`, or `@avahoffman`). We greatly appreciate any feedback! We are always looking for ways to improve OTTR so more open source courses can be made! + +--- + +**Still need help?** [Contact us](contact.qmd) → diff --git a/getting_started.qmd b/getting_started.qmd index 50387b0..e377f28 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -1,39 +1,435 @@ --- title: "Getting Started" -output: html_document +toc-depth: 4 --- -Select the flavor of OTTR are you using to access setup instructions. +## Prerequisites for using OTTR -::: {.panel-tabset group="ottrType"} +OTTR relies on R Markdown/Quarto and GitHub Actions. You do not need to be an expert in either to get started. We will guide you through the process! However, we recommend spending a few minutes familiarizing yourself with both before diving in. -## OTTR Courses +Please check out these resources if you are not familiar with R Markdown/Quarto. Note that OTTR is also compatible with regular Markdown websites. -Tab Content +- If you aren't familiar with **Quarto**, you can get started [here](https://quarto.org/docs/get-started/). +- If you aren't familiar with **R Markdown**, you can find RStudio's lessons [here](https://rmarkdown.rstudio.com/lesson-1.html). +- If you aren't familiar with **Markdown**, this [site](https://www.markdownguide.org/getting-started/) is a nice introduction. -Example: Provide an example repo +If you are not familiar with **Git and GitHub**, we recommend going through these chapters from our Reproducibility courses: -## OTTR Web +- [Making your project open source with GitHub](https://jhudatascience.org/Reproducibility_in_Cancer_Informatics/making-your-project-open-source-with-github.html) +- [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) -Tab Content +We offer two suggested approaches based on your comfort with Git and GitHub: -Example: Provide an example repo +- **OTTR Entry Level**: Conducted entirely through the GitHub web browser — no local Git setup needed. +- **OTTR Advanced**: For those familiar with (or interested in learning) Git. Involves some additional learning but is highly beneficial for version control beyond OTTR. -## OTTR Quarto Courses +If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.gitkraken.com/) as a Git client to facilitate branch management. -Tab Content +--- + +## Courses + + +### Quarto Courses + + + +**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) + +A Quarto-based course template. Recommended for new projects. + +#### 1. Create a repository from the template + +On the [landing page of the OTTR_Quarto repository](https://github.com/ottrproject/OTTR_Quarto), locate the green **Use this template** button in the upper right corner. Click it, then select **Create a new repository** and follow the instructions. + +![](resources/screenshots/template_button.png) + +#### 2. Name your repository and fill in a short description + +Enter a name in the **Repository name** field and provide a brief description in the **Description** box. + +![](resources/screenshots/creating_new_course_repo.png) + +#### 3. Ensure your repository is set to `public` + +Make sure to set it [to a public repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). The rendered pull request preview won't work on private repositories. + +#### 4. Click `Create repository from template` to proceed + +After creating your repository, issues with setup instructions will be automatically filed. Navigate to the **Issues** tab and follow the instructions there. + +#### 5. Check your GitHub Actions settings + +Go to **Settings** > **Actions** > **General**. Make sure you have: + +1. Given **Read and write permissions** +2. Checked **Allow GitHub Actions to create and approve pull requests** + +Then click **Save**. + + + +#### 6. Set up your GitHub personal access token + +Go to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets** and click **New repository secret**. + +- **Name**: `GH_PAT` (this exact name is required) +- **Secret**: create a [classic personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `repo` and `workflow` scopes checked. + +#### 7. Set up GitHub Pages + +In your repository, go to **Settings** > **Pages** and configure: + +- **Source**: Deploy from a branch +- **Branch**: `main`, folder `/docs` + +Click **Save**, then check **Enforce HTTPS** at the bottom of the page. + +![](resources/screenshots/change_https.png) + +

+**Warning**: If you visit your URL before pushing any file changes, you may see a 404 error. Check after filing your first pull request. +

+ +#### 8. Enroll for updates (recommended) + +Add `jhudsl-robot` as a collaborator with write access (**Settings** > **Collaborators & Teams**), then add your repository name to the relevant sync file. [See full instructions here](https://www.ottrproject.org/getting_started.html#which-sync-file-should-you-edit). + +#### Start writing! + +Content is written in `.qmd` files using standard [Quarto syntax](https://quarto.org/docs/authoring/markdown-basics.html). + +--- + +[Next Steps](next_steps.qmd) → + +### R Markdown Courses + + + +**Template repository:** [ottrproject/OTTR_Template](https://github.com/ottrproject/OTTR_Template) + +An R Markdown / Bookdown-based course template with a table of contents on the side. Supports publishing to Coursera and Leanpub. Best choice when you have existing `.Rmd` files to build on. + + + +#### 1. Create a repository from the template + +On the [landing page of the OTTR_Template repository](https://github.com/ottrproject/OTTR_Template), locate the green **Use this template** button in the upper right corner. Click it, then select **Create a new repository** and follow the instructions to configure your repository. + +![](resources/screenshots/template_button.png) + +#### 2. Name your repository and fill in a short description + +Enter a name in the **Repository name** field and provide a brief description in the **Description** box. + +![](resources/screenshots/creating_new_course_repo.png) + +#### 3. Ensure your repository is set to `public` + +Make sure to set it [to a public repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). The rendered pull request preview won't work on private repositories (though you can preview content locally). + +#### 4. Click `Create repository from template` to proceed + +After creating your repository, issues with setup instructions will be automatically filed. Navigate to the **Issues** tab and follow the instructions there. + +#### 5. Check your GitHub Actions settings + +Go to **Settings** > **Actions** > **General**. Make sure you have: + +1. Given **Read and write permissions** +2. Checked **Allow GitHub Actions to create and approve pull requests** + +Then click **Save**. + + + +#### 6. Set up your GitHub personal access token + +To give OTTR's robots the permissions they need, set a GitHub Secret called `GH_PAT`. Go to **Settings** > **Secrets and variables** > **Actions** and scroll down to **Repository secrets**. ([Read more about GitHub Secrets here](https://docs.github.com/en/actions/security-guides/encrypted-secrets).) + +If you have organization admin privileges and plan to make multiple courses, you can set `GH_PAT` as an organization secret so you only need to do this once. + +- Click **New repository secret** / **New organization secret**. +- Under **Name**, enter `GH_PAT` (this exact name is required). +- For **Secret**: create a [classic personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `repo` and `workflow` scopes checked. Copy and paste it as the secret value. + +If you encounter any problems, [report an issue here](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=&labels=bug&projects=&template=course-problem-report.md&title%5B%5D=Problem). + +#### 7. Set up GitHub Pages + +In your repository, go to **Settings** > **Pages** and configure: + +- **Source**: Deploy from a branch +- **Branch**: `main`, folder `/docs` + +Click **Save**, then check **Enforce HTTPS** at the bottom of the page. + +![](resources/screenshots/change_https.png) + +Your course URL will be `username.github.io/your-repo-name`, displayed under **Settings** > **Pages**. You can customize the base GitHub Pages URL (e.g., `jhudatascience.org`). + +

+**Warning**: If you visit your URL before pushing any file changes, you may see a 404 error — nothing has been triggered to render yet. Check the URL after filing your first pull request. +

+ +#### 8. Enroll for updates (recommended) + +The templates are always a work in progress. When updates are made to non-content files (checks, automation), pull requests are automatically filed to downstream repositories. + +**To get sync updates, add `jhudsl-robot` as a collaborator** with write access: go to **Settings** > **Collaborators & Teams** > **Add people** and search for `jhudsl-robot`. + + + +Then add your repository name to the [OTTR_Template sync file](https://github.com/ottrproject/OTTR_Template/blob/main/.github/sync.yml). + +If you're **not** a member of the jhudsl GitHub organization, you can: + +- Submit your repo info via the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) +- [Open an issue](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) with your repo name and we'll add it +- Fork the repo, edit `sync.yml` by adding your repo name where it says `#NEW REPO HERE#`, and open a PR + +![](resources/screenshots/edit-sync.yml.png) + +| Repository | Issue Links | +|:---:|:---| +| OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | +| OTTR_Quizzes | [Open an issue](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | + +

+_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._ +

+ +--- + +[Next Steps](next_steps.qmd) → + +## Websites + +### Quarto Websites + + + +**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) + +A Quarto-based website template. The modern standard — recommended for all new projects. + +#### 1. Create a repository from the template + +On the [landing page of the OTTR_Quarto repository](https://github.com/ottrproject/OTTR_Quarto), locate the green **Use this template** button in the upper right corner. Click it, then select **Create a new repository** and follow the instructions. + +![](resources/screenshots/template_button.png) + +#### 2. Name your repository and fill in a short description + +Enter a name in the **Repository name** field and provide a brief description in the **Description** box. -Example: Provide an example repo +![](resources/screenshots/creating_new_course_repo.png) -## OTTR Quarto Web +#### 3. Ensure your repository is set to `public` -Tab Content +Make sure to set it [to a public repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). The rendered pull request preview won't work on private repositories. -Example: Provide an example repo +#### 4. Click `Create repository from template` to proceed -## OTTR Metricminer Dashboard +After creating your repository, issues with setup instructions will be automatically filed. Navigate to the **Issues** tab and follow the instructions there. -Tab Content +#### 5. Check your GitHub Actions settings + +Go to **Settings** > **Actions** > **General**. Make sure you have: + +1. Given **Read and write permissions** +2. Checked **Allow GitHub Actions to create and approve pull requests** + +Then click **Save**. + + + +#### 6. Set up your GitHub personal access token + +Go to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets** and click **New repository secret**. + +- **Name**: `GH_PAT` (this exact name is required) +- **Secret**: create a [classic personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `repo` and `workflow` scopes checked. + +#### 7. Set up GitHub Pages + +In your repository, go to **Settings** > **Pages** and configure: + +- **Source**: Deploy from a branch +- **Branch**: `main`, folder `/docs` + +Click **Save**, then check **Enforce HTTPS** at the bottom of the page. + +![](resources/screenshots/change_https.png) + +

+**Warning**: If you visit your URL before pushing any file changes, you may see a 404 error. Check after filing your first pull request. +

+ +#### 8. Enroll for updates (recommended) + +Add `jhudsl-robot` as a collaborator with write access (**Settings** > **Collaborators & Teams**), then add your repository name to the relevant sync file. [See full instructions here](https://www.ottrproject.org/getting_started.html#which-sync-file-should-you-edit). + +#### Start writing! + +Content is written in `.qmd` files using standard [Quarto syntax](https://quarto.org/docs/authoring/markdown-basics.html). + +--- + +[Next Steps](next_steps.qmd) → + +### R Markdown Websites + +**Template repository:** [ottrproject/OTTR_Template_Website](https://github.com/ottrproject/OTTR_Template_Website) + +An R Markdown / Bookdown-based website template with a nav bar on top — like the site you're looking at now. Best choice if you have existing `.Rmd` files to build on. + +#### 1. Create a repository from the template + +On the [landing page of the OTTR_Template_Website repository](https://github.com/ottrproject/OTTR_Template_Website), locate the green **Use this template** button in the upper right corner. Click it, then select **Create a new repository** and follow the instructions. + +![](resources/screenshots/template_button.png) + +#### 2. Name your repository and fill in a short description + +Enter a name in the **Repository name** field and provide a brief description in the **Description** box. + +![](resources/screenshots/creating_new_course_repo.png) + +#### 3. Ensure your repository is set to `public` + +Make sure to set it [to a public repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). The rendered pull request preview won't work on private repositories. + +#### 4. Click `Create repository from template` to proceed + +After creating your repository, issues with setup instructions will be automatically filed. Navigate to the **Issues** tab and follow the instructions there. + +#### 5. Check your GitHub Actions settings + +Go to **Settings** > **Actions** > **General**. Make sure you have: + +1. Given **Read and write permissions** +2. Checked **Allow GitHub Actions to create and approve pull requests** + +Then click **Save**. + + + +#### 6. Set up your GitHub personal access token + +Go to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets** and click **New repository secret**. + +- **Name**: `GH_PAT` (this exact name is required) +- **Secret**: create a [classic personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `repo` and `workflow` scopes checked. + +If you encounter any problems, [report an issue here](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose). + +#### 7. Set up GitHub Pages + +In your repository, go to **Settings** > **Pages** and configure: + +- **Source**: Deploy from a branch +- **Branch**: `main`, folder `/docs` + +Click **Save**, then check **Enforce HTTPS** at the bottom of the page. + +![](resources/screenshots/change_https.png) + +

+**Warning**: If you visit your URL before pushing any file changes, you may see a 404 error. Check after filing your first pull request. +

+ +#### 8. Enroll for updates (recommended) + +Add `jhudsl-robot` as a collaborator with write access (**Settings** > **Collaborators & Teams**), then add your repository name to the [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml). + +If you're **not** a member of the jhudsl GitHub organization, you can: + +- Submit your repo info via the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) +- [Open an issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) with your repo name and we'll add it + +| Repository | Issue Links | +|:---:|:---| +| OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) | + +

+_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._ +

+ +--- + +[Next Steps](next_steps.qmd) → + +## Dashboards + +### Metricminer Dashboard + +**Template repository:** [ottrproject/metricminer-dashboard](https://github.com/ottrproject/metricminer-dashboard) + +A dashboard template powered by the [`metricminer`](https://www.metricminer.org/) R package. Displays metrics from GitHub, Google Analytics, Google Forms, CRAN, Calendly, and more. + +#### 1. Create a repository from the template + +On the [landing page of the metricminer-dashboard repository](https://github.com/ottrproject/metricminer-dashboard), locate the green **Use this template** button in the upper right corner. Click it, then select **Create a new repository** and follow the instructions. + +![](resources/screenshots/template_button.png) + +#### 2. Name your repository and fill in a short description + +Enter a name in the **Repository name** field and provide a brief description in the **Description** box. + +#### 3. Ensure your repository is set to `public` + +Make sure to set it [to a public repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). + +#### 4. Click `Create repository from template` to proceed + +After creating your repository, navigate to the **Issues** tab and follow any automatically filed setup instructions. + +#### 5. Check your GitHub Actions settings + +Go to **Settings** > **Actions** > **General**. Make sure you have: + +1. Given **Read and write permissions** +2. Checked **Allow GitHub Actions to create and approve pull requests** + +Then click **Save**. + + + +#### 6. Set up your GitHub personal access token + +Go to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets** and click **New repository secret**. + +- **Name**: `GH_PAT` (this exact name is required) +- **Secret**: create a [classic personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with `repo` and `workflow` scopes checked. + +#### 7. Configure your data source credentials + +Set up credentials for whichever metric sources you want to collect from. Each source requires its own repository secret — see the [metricminer documentation](https://www.metricminer.org/) for the specific tokens needed (Google Analytics, GitHub, etc.). + +#### 8. Set up GitHub Pages + +In your repository, go to **Settings** > **Pages** and configure: + +- **Source**: Deploy from a branch +- **Branch**: `main`, folder `/docs` + +Click **Save**, then check **Enforce HTTPS** at the bottom of the page. + +

+**Warning**: If you visit your URL before pushing any file changes, you may see a 404 error. Check after filing your first pull request. +

+ +#### Start customizing! + +Edit the `.Rmd` files in the repository to configure which metrics to display and how to arrange them. See [metricminer.org](https://www.metricminer.org/) for full documentation. + +--- + +If you wish to contribute to OTTR, please take a look at our [Code of Conduct](https://github.com/ottrproject/OTTR_Template/blob/main/code_of_conduct.md). + +--- -Example: Provide an example repo -::: +**Now that your repository is set up, see [Next Steps](next_steps.qmd) → for what to do next.** diff --git a/index.qmd b/index.qmd index 012e643..f2032e8 100644 --- a/index.qmd +++ b/index.qmd @@ -1,9 +1,112 @@ --- title: "** OTTR - Website and Online Course Tools**" -output: - html_document +toc: false --- + + + @@ -11,6 +114,165 @@ output:

OTTR (Open-source Tools for Training Resources ) is a set of tools and templates to help you make **websites, online courses, and dashboards** more easily (and for free)!

+ +
+
+
+
+ + + + +### Quarto vs. R Markdown + +OTTR templates come in two flavors based on which document format you use to write content: **R Markdown** (`.Rmd`) and **Quarto** (`.qmd`). + +- **Quarto** is the next-generation successor to R Markdown, developed by Posit. It supports R, Python, Julia, and Observable JS, and offers a more consistent syntax and better cross-language support. It is the recommended choice for new projects. +- **R Markdown** is a widely used format that combines plain text, Markdown formatting, and R code chunks into a single document. It has a large ecosystem and is a solid choice if you already have `.Rmd` files or are following older OTTR tutorials. + +If you're starting fresh and have no existing `.Rmd` files, go with a Quarto template. If you have existing `.Rmd` content or are working with a team already using R Markdown, the R Markdown templates are a fine choice. + +--- +
@@ -83,7 +345,7 @@ Please cite our [OTTR manuscript here!](https://www.tandfonline.com/doi/full/10.
- +
diff --git a/more_features_borrowing.qmd b/more_features_borrowing.qmd index d91b59d..7cb0757 100644 --- a/more_features_borrowing.qmd +++ b/more_features_borrowing.qmd @@ -89,3 +89,7 @@ Learn more about templates [here](https://bookdown.org/yihui/rmarkdown-cookbook/
+ +--- + +← [Next Steps](next_steps.qmd)   [Troubleshooting](faqs.qmd) → diff --git a/more_features_credits.qmd b/more_features_credits.qmd index 19f0328..196ed51 100644 --- a/more_features_credits.qmd +++ b/more_features_credits.qmd @@ -91,3 +91,7 @@ In Coursera, you can add the credits table URL as an ungraded plugin ([the same In Leanpub, make sure that your About.md file in your manuscript folder is listed in your Book.txt file and this Credits table will automatically be incorporated into your Leanpub course.
+ +--- + +**← Back to:** [Next Steps](next_steps.qmd) · **Also see:** [Citing Sources](more_features_sources.qmd) · [Customizing Style](customize-style.qmd) diff --git a/more_features_ganalytic.qmd b/more_features_ganalytic.qmd index d04ddc9..6221bed 100644 --- a/more_features_ganalytic.qmd +++ b/more_features_ganalytic.qmd @@ -1,51 +1,162 @@ --- -title: "More Features: Google Analytics Integration" -output: - html_document +title: "Google Analytics" --- -## Google Analytics +# Set Up Google Analytics -If you would like to add Google Analytics to track traffic to your course, you can do the following: +Follow these steps to enable traffic tracking for your OTTR course or website. -1. Get a **Google Analytics account** (if you do not already have one): [https://analytics.google.com/analytics](https://analytics.google.com/analytics) -![](resources/images/GA_account.png) -Note that in creating an account you will need to agree to some terms. Currently it is free to get Google analytics data as long as your course does not exceed a very high user rate. +**1. Create a Google Analytics account** (if you do not already have one): https://analytics.google.com/analytics -Check to make sure that the terms work for you -![](resources/images/GA_terms.png) +Click on **Start measuring**. +![](resources/images/GA_start.png) -1. If you already have an account or navigated away from where you started - Go to the **Admin tab** (lower left button that looks like a gear) +You will need to agree to Google's terms during account creation. Tracking is currently free as long as your course does not exceed a very high user rate. + +**2. Create a new Property** — fill in a name and details, and select the options that reflect how you intend to use Google Analytics. -1. Set up a new **property** (fill out name and details, select options about tracking traffic for how you intend to use Google Analytics) ![Google Analytics Property creation](resources/images/GA_Create_Property.png) -![Google Analytics Property](resources/images/GA_Property_setup.png) +![Google Analytics Property setup](resources/images/GA_Property_setup.png) ![Google Analytics Property choices](resources/images/GA_property.png) -1. Add a **stream** to your property, choose the **Web** option. +**3. Accept Terms** + +To use Google Analytics you must first accept the terms of service agreement for your country / region. + +**4. Add a Data Stream** to your property — choose the **Web** option. + ![Google Analytics stream options](resources/images/GA_web.png) +**5. Enter the URL** for your course. Note: the `https://` portion is selected from a dropdown to the left of the URL field — do not include it in the text box. Click on _Create and continue_. + +![Google Analytics stream link](resources/images/GA_stream_link.png) +![Google Analytics stream link correct format](resources/images/GA_stream_link_correct.png) + +**6. Copy the code chunk** provided on the resulting page. It will look like this (with your unique ID in place of `G-XXXXXXXXXX`): + +```html + + + +``` + +
+ +# Configure Your OTTR Repo + +:::: {.columns} + +::: {.column width="50%"} + +## For R Markdown Courses + +**Update `GA_Script.html`** — replace the entire contents of the file with the code chunk you copied from Google Analytics: + +```html + + + +``` + +![GA_Script.html with ID filled in](resources/images/GA_Script_ID.png) + +**`_output.yml` is already configured** in the updated OTTR template — no manual changes needed. It should include: + +```yaml +includes: + in_header: GA_Script.html + before body: ... +``` + +![output.yml with GA included](resources/images/output_GA.png) + +::: -1. Fill in your stream information with the **link** for your course (note you may need to remove https as this is part of a pull down menu to the left of where you paste your link) -![Google Analytics stream](resources/images/GA_stream_link.png) -![Google Analytics stream](resources/images/GA_stream_link_correct.png) +::: {.column width="50%"} +## For Quarto Courses -1. On the resulting page you will see a **Measurement ID**. Copy this ID and paste it in the GA_Script.html file in the template replacing the fields that say {MeasurementID} including the curly brackets. For example, if your ID was `G-ABC123`, then the line `gtag('config', '{MeasurementID}');` would become `gtag('config', 'G-ABC123');`. -![](resources/images/GA_ID.png) -![](resources/images/GA_Script_ID.png) +**Update `GA_Script.html`** — replace the entire contents of the file with the code chunk you copied from Google Analytics (same as for R Markdown courses). -1. Add a line to the _output.yml file above the line that starts with `before body:` (i.e. nested under `includes`). This line should be `in_header: GA_Script.html`. Make sure this line is indented to the same level as the `before body:` line. -![](resources/images/output_GA.png) +The `GA_Script.html` file is included via `include-in-header` in `_quarto.yml`: -1. **Rerender** your course by making a change to one of your chapter RMD files in a pull request and pushing and merging the pull request. This will cause new html files to be made for each chapter in the `docs` folder. The Google Analytics code should now be in each of the html files - you can check by searching for `Google Analytics`. +```yaml +format: + html: + include-in-header: GA_Script.html +``` -1. Go back to [Google Analytics](https://analytics.google.com/analytics) and log in if you need to. +The updated template handles this — you only need to paste in your copied code chunk. -1. Check on the **Reports** button on the top of the far left icon menu. The icon looks like a bar chart. If you open up a browser window to your hosted course online, then you should see yourself as 1 user in the last 30 minutes. +::: +:::: -![Google Analytics Reports](resources/images/GA_reports.png) -![Check Google Analytics](resources/images/GA_check.png) +
+ +# Trigger a Re-render + +After updating `GA_Script.html`, the GitHub Action will automatically re-render your course because the updated OTTR template watches for changes to `GA_Script.html`: + +```yaml +# In .github/workflows/render-all.yml +on: + push: + paths: + - '*.Rmd' + - 'assets/*' + - '*.yml' + - 'GA_Script.html' # <-- triggers render on GA changes +``` + +You can verify the Google Analytics code was included by opening any rendered HTML file in `docs/` and searching for `Google Analytics`. + +> **Note:** If you are working with an older template, you may need to manually trigger the `render_all` workflow. Make sure both `_output.yml` and `GA_Script.html` are updated with matching file names and the correct code chunk. Occasionally this also requires setting up a `GH_PAT` for the repo (with `actions` and `repo` permissions) — not just the organization. + +
+ +# Verify Traffic Is Being Tracked + +1. Log in to Google Analytics. + +1. Click the **gear icon** (lower left) → **Data Collection and Modification** → **Data Streams**. + +1. Click on your stream — it will indicate whether traffic has been received. + +1. To test, click **Test** on the stream page. Even if the test passes, **also open your live course URL** and check Google Analytics to confirm you appear as a visitor. + +1. Click the **Home button** in Google Analytics — it should say **"Data collection is active"**. + +1. Check the **Reports** tab (bar chart icon, upper left). If you open your course in a browser, you should see yourself counted as 1 user in the last 30 minutes. + +![Google Analytics Reports view](resources/images/GA_reports.png) +![Verifying traffic in Google Analytics](resources/images/GA_check.png) + +
+ +# Troubleshooting + +| Issue | What to Check | +|------------------------------------|----------------------------------------------------| +| No data showing in GA | Make sure the **code chunk** in `GA_Script.html` was copied correctly from Google Analytics and contains the right ID (`G-XXXXXXXXXX`) | +| Data stream shows no traffic | Check that the **URL** in the stream matches your course URL — watch for `https` vs `http` | +| Old template not rendering GA | Manually run the `render_all` workflow; confirm both `_output.yml` and `GA_Script.html` are updated with the correct code chunk, and that the `GA_Script.html` filename is consistent in both files | +| Render not triggering | Ensure `GH_PAT` is set up for the repo (with `actions` and `repo` permissions), not just the organization | + + + +--- -1. Enjoy the data about how people are using your course! +**← Back to:** [Next Steps](next_steps.qmd) · **Having issues?** [Troubleshooting](faqs.qmd) diff --git a/more_features_gdoc.qmd b/more_features_gdoc.qmd index 225ec3e..965b79e 100644 --- a/more_features_gdoc.qmd +++ b/more_features_gdoc.qmd @@ -14,3 +14,7 @@ Google Docs can be a great way to get feedback from collaborators who aren't com - Then as comments and suggestions trickle in, a lead author who is comfortable with the OTTR process can incorporate those comments into an existing or new pull request which can checked for its rendering and eventually added to the `main` content branch.
+ +--- + +← [Next Steps](next_steps.qmd)   [Troubleshooting](faqs.qmd) → diff --git a/more_features_sources.qmd b/more_features_sources.qmd index 6da160c..3c39767 100644 --- a/more_features_sources.qmd +++ b/more_features_sources.qmd @@ -39,3 +39,7 @@ Alternatively, you can add a header for this list of references as the last head If you would like to suppress having references listed at the end of each chapter, you can add a line that says `split_bib: false` to your `_output.yml` file. ![](resources/images/false_split_ref.png) + +--- + +**← Back to:** [Next Steps](next_steps.qmd) · **Also see:** [Giving Credits](more_features_credits.qmd) · [Customizing Style](customize-style.qmd) diff --git a/next_steps.qmd b/next_steps.qmd index 6e88182..5409ea3 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -1,21 +1,201 @@ --- title: "Next Steps" -output: html_document +toc-depth: 5 --- Now that you've setup a shell for your OTTR repository, there are some next steps that you **need** to take, and some steps that we **highly recommend**. Additionally, there are further customizations you may want to consider. -::: {.panel-tabset group="nextStepType"} - ## Necessary Next Steps -Tab Content ... Visit here to learn more +### Enroll for sync updates + +The OTTR templates are always a work in progress — new features are added and bugs are smoothed out over time. [Your feedback is greatly appreciated](https://github.com/ottrproject/OTTR_Template/issues/new/choose). When updates are made to non-content files (checks, automation), pull requests are automatically filed to downstream repositories made from the template. + +#### Add `jhudsl-robot` as a collaborator + +*You can skip this step if your course is in the `jhudsl` organization.* + +To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a collaborator with write access: + +1. In your repository, go to **Settings** > **Collaborators & Teams** and click **Add people**. +2. Search for and add `jhudsl-robot`. +3. If prompted, choose the **Write** option, then click **Add jhudsl-robot to this repository**. + + + +#### Which sync file should you edit? + +Add your repository name to the `.github/sync.yml` file of the OTTR template you created your repository from: + +- [OTTR_Template sync file](https://github.com/ottrproject/OTTR_Template/blob/main/.github/sync.yml) — for R Markdown courses +- [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites +- [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes + +#### If you are part of the jhudsl GitHub organization + +1. Open the relevant sync file above and click the pencil icon to edit. +2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/edit-sync.yml.png) + +3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. +4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. + +#### If you are not part of the jhudsl GitHub organization + +Use one of these options: + +- **Google Form** — submit your organization/username and repo name in the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) and we'll make the edit for you. +- **Open an issue** — use the links in the table below and provide your repo info; we'll update `sync.yml` for you. +- **Fork and PR** — fork the template repo, edit `sync.yml` on a new branch adding your repo name where it says `#NEW REPO HERE#`, commit, and open a pull request. Add a comment tagging `@kweav` so we see it. + +| Repository | Issue Links | +|:---:|:---| +| OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | +| OTTR_Quizzes | [Open an issue](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | +| OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) | + +

+_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._ +

+ + +### Customizing branding and style + +Once your repository is set up, it's worth updating the visual identity of your course or website to reflect your project. For full instructions, see the [Customizing Style page](customize-style.qmd). + +**Key things to update:** + +- **Title** — set in the YAML header of `index.Rmd` (or `index.qmd` for Quarto). +- **Style set** — the template defaults to the JHU Data Science Lab style. If you are building an ITN or DataTrail course, copy the relevant files from the `style-sets/` folder to switch styles. +- **Favicon** — convert your logo to `.ico` format using [favicon.io](https://favicon.io/favicon-converter/), save it in `assets/`, and reference it in the YAML header. +- **Logo** — logos in the table of contents sidebar are configured via `_output.yml`. Update the image URL and the link to your GitHub repo. +- **Colors** — text colors can be changed by editing `assets/style.css`. Search for `#012d72` (dark blue) or `#68ace5` (light blue) and replace with your preferred hex codes. ## Highly Recommended Next Steps -Tab Content ... Visit here to learn more +### Clean out template placeholder files + +The OTTR template ships with example content files to show you the structure. Once you're ready to start writing, replace these with your own content. + +**Safe to delete:** + +- Example chapter files (e.g., `01-intro.Rmd`, `02-chapter_of_course.Rmd`, `03-chapter_of_course.Rmd`) +- `index.Rmd` placeholder text (edit in place rather than deleting) +- Any images in `resources/images/` that were part of the example content + +**Do NOT delete:** + +- Anything inside `.github/workflows/` — these run all the automated checks and rendering +- `assets/` — contains styling files +- `resources/` — contains the spell-check dictionary and screenshot helpers +- Configuration files: `_bookdown.yml`, `_output.yml`, `book.bib`, `_quarto.yml` + +### Update the README + +The `README.md` in your repository comes with template placeholder text. Update it to describe what your course or website is about, who it's for, and how to contribute or report issues. A clear README helps collaborators and visitors understand your project at a glance. + +At minimum, update: + +- The title and description +- Any links that point to the template repository (replace with your own repo URL) +- Author and contact information + +### Add a license + +Adding a license to your repository clarifies how others can use and share your content. For open educational resources, [Creative Commons Attribution 4.0 (CC BY 4.0)](https://choosealicense.com/licenses/cc-by-4.0/) is a common choice — it allows reuse with attribution. + +To add a license on GitHub: + +1. Go to your repository's main page. +2. Click **Add file** > **Create new file** and name it `LICENSE`. +3. GitHub will offer a license picker — select your preferred license and commit. + +### Add your repository link to the sidebar + +Linking your GitHub repository from the sidebar makes it easy for readers to find the source, suggest edits, or file issues. + +For **R Markdown courses**, update `_output.yml`: + +```yaml +bookdown::gitbook: + config: + edit: + link: https://github.com/YOUR-ORG/YOUR-REPO/edit/main/%s + text: "Suggest an edit" + download: no + sharing: no +``` + +For **Quarto**, update `_quarto.yml`: + +```yaml +website: + repo-url: https://github.com/YOUR-ORG/YOUR-REPO + repo-actions: [edit, issue] +``` + +Replace `YOUR-ORG/YOUR-REPO` with your actual organization and repository name. + +### Set up a feedback channel + +Making it easy for learners to report problems or leave feedback improves your course over time. Two good approaches: + +**GitHub issue templates** — add structured issue forms so readers can report content errors, broken links, or general feedback directly from your repo. You can use [OTTR's example issue templates](https://github.com/ottrproject/OTTR_Template/tree/main/.github/ISSUE_TEMPLATE) as a starting point. + +**Google Form link** — for audiences less familiar with GitHub, add a feedback Google Form link to your course. In `_output.yml`, you can surface this in the sharing config: + +```yaml +bookdown::gitbook: + config: + sharing: + facebook: false + twitter: false + all: [] +``` + +Then add a direct link to your form in `index.Rmd` or your course footer. For automated responses, [Zapier](https://zapier.com) can connect Google Form submissions to email notifications, Slack alerts, or GitHub issues. + +### Giving credits to contributors + +OTTR courses include a credits table to acknowledge everyone who contributed — instructors, editors, publishers, and template engineers. For full instructions, see the [Giving Credits page](more_features_credits.qmd). + +**Key things to update:** + +- **`About.Rmd`** — already included in the template. Fill in author names for each role, remove inapplicable rows, and make sure role names grammatically match (singular vs. plural). +- **Required rows** — all courses should include rows for Template Publishing Engineers, Publishing Maintenance Engineer, Technical Publishing Stylists, and Package Developers. See the [full credits table reference](https://bit.ly/course-credits-table). +- **Coursera** — add the credits table URL as an ungraded plugin at the start of your course, right after the introduction. +- **Leanpub** — ensure `About.md` is listed in `Book.txt` and it will be included automatically. + +### Citing sources + +OTTR courses use BibTeX-style references managed through a `book.bib` file. For full instructions, see the [Citing Sources page](more_features_sources.qmd). + +**Key things to know:** + +- **Add references** to `book.bib` in alphabetical order. For articles with a DOI, use [doi2bib.org](https://www.doi2bib.org/) or [ZoteroBib](https://zbib.org/) to generate a BibTeX entry to copy in. +- **Cite in text** using `@key` (inline) or `[@key]` (parenthetical). Separate multiple citations with semicolons: `[@key-1; @key-2]`. +- **References list** — keep `References.Rmd` as the last file in `_bookdown.yml` so the full reference list appears at the end of your course. +- **Suppress per-chapter references** by adding `split_bib: false` to `_output.yml`. + +### Setting up Google Analytics + +Adding Google Analytics to your OTTR course or website lets you track how people are finding and using your content. For full setup instructions, see the [Google Analytics Integration page](more_features_ganalytic.qmd). + +**Quick overview:** + +1. Create a [Google Analytics account](https://analytics.google.com/analytics) and set up a new property with a **Web** data stream for your course URL. +2. Copy the ` + + ### Quarto vs. R Markdown @@ -271,6 +277,17 @@ OTTR templates come in two flavors based on which document format you use to wri If you're starting fresh and have no existing `.Rmd` files, go with a Quarto template. If you have existing `.Rmd` content or are working with a team already using R Markdown, the R Markdown templates are a fine choice. +::: {.callout-warning} +## R Markdown is no longer being actively updated + +Posit has shifted its focus to Quarto as the next-generation publishing system. R Markdown remains functional but **will not receive new features**. For any new project, start with a Quarto template. + +**Resources for Quarto-fying your content:** + +- [quartify](https://ddotta.github.io/quartify/articles/getting-started.html): an R package that automates conversion of R Markdown files to Quarto +- [Transitioning from R Markdown to Quarto](https://github.com/Openscapes/quarto-website-tutorial/blob/main/transition-from-rmarkdown.qmd): a practical guide from Openscapes +::: + ---
}}" + href: more_features_credits.qmd - text: "---" - text: "Customize" - text: "Style {{< fa palette title='A palette' >}}" @@ -41,8 +43,6 @@ website: href: more_features_ganalytic.qmd - text: "Citing sources {{< fa quote-left title='A left quotation mark' >}}" href: more_features_sources.qmd - - text: "Giving credits {{< fa award title='An award' >}}" - href: more_features_credits.qmd - text: "Google Docs {{< fa file title='a file folder' >}}" href: more_features_gdoc.qmd - text: "Borrowing chapters {{< fa bookmark title='A bookmark' >}}" From b6a7dd88d135f63b04cb34acba962126ba11214a Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 1 Apr 2026 16:52:42 -0400 Subject: [PATCH 07/37] add ava and kate to contact page --- contact.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contact.qmd b/contact.qmd index d0f683c..0052b09 100644 --- a/contact.qmd +++ b/contact.qmd @@ -7,6 +7,8 @@ output: If you have questions please contact: - Carrie Wright (cwright2@fredhutch.org) +- Ava Hoffman (ahoffma2@fredhutch.org) +- Kate Isaac (kisaac@fredhutch.org) --- From 6020f320a64f6b0525bfd77895a3e9ce12a7ac77 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Fri, 3 Apr 2026 12:44:57 -0400 Subject: [PATCH 08/37] fixing errors from ottr check --- resources/dictionary.txt | 3 +++ resources/ignore-urls.txt | 2 ++ 2 files changed, 5 insertions(+) diff --git a/resources/dictionary.txt b/resources/dictionary.txt index afa33c0..635a59c 100644 --- a/resources/dictionary.txt +++ b/resources/dictionary.txt @@ -95,3 +95,6 @@ gcse searchbox README Zapier +callout +Openscapes +quartify diff --git a/resources/ignore-urls.txt b/resources/ignore-urls.txt index 3139a2c..c5eec02 100644 --- a/resources/ignore-urls.txt +++ b/resources/ignore-urls.txt @@ -1,3 +1,5 @@ https://username.github.io/repository_name/ ${r.url} getting_started.html +r.url +choose_template.html From cf7408f0c5b2f2afc864404a9cf94c731a6f01ae Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Fri, 3 Apr 2026 12:48:21 -0400 Subject: [PATCH 09/37] update metricminer example --- examples.qmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples.qmd b/examples.qmd index e9d4191..bc84904 100644 --- a/examples.qmd +++ b/examples.qmd @@ -122,11 +122,11 @@ Explore courses, websites, and templates built with OTTR. If you've made somethi
Dashboard -

Metricminer Dashboard

-

A dashboard template powered by the metricminer R package. Tracks GitHub, Google Analytics, Google Forms, CRAN, Calendly, and more.

+

Open Case Studies Metrics Dashboard

+

This website shows metrics related to the Open Case Studies project (OCS). OCS is an educational archive of data analysis guides using real-world data to help learners engage with data science and statistics topics.

- GitHub - metricminer.org + View dashboard + GitHub
From cdfbe3609e470f50dd5a4222410a9131b44b363a Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Fri, 3 Apr 2026 12:50:07 -0400 Subject: [PATCH 10/37] add fhdsl to enroll sync --- enroll_sync.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/enroll_sync.qmd b/enroll_sync.qmd index c921e4d..28e4ab5 100644 --- a/enroll_sync.qmd +++ b/enroll_sync.qmd @@ -6,7 +6,7 @@ The OTTR templates are always a work in progress. New features are added and bug ## Add `jhudsl-robot` as a collaborator -*You can skip this step if your course is in the `jhudsl` organization.* +*You can skip this step if your course is in the `jhudsl` or `fhdsl` organization.* To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a collaborator with write access: @@ -24,7 +24,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you - [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites - [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes -## If you are part of the jhudsl GitHub organization +## If you are part of the `jhudsl` or `fhdsl` GitHub organization 1. Open the relevant sync file above and click the pencil icon to edit. 2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. @@ -34,7 +34,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you 3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. 4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. -## If you are not part of the jhudsl GitHub organization +## If you are not part of the `jhudsl` or `fhdsl` GitHub organization Use one of these options: From a93ef42768f61904c6f534e13761abd3514e8549 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Sat, 4 Apr 2026 15:14:52 -0400 Subject: [PATCH 11/37] adding publishing & start writing pages --- _quarto.yml | 4 + publishing.qmd | 384 ++++++++++++++++++++++ writing_content_courses.qmd | 615 ++++++++++++++++++++++++++++++++++++ 3 files changed, 1003 insertions(+) create mode 100644 publishing.qmd create mode 100644 writing_content_courses.qmd diff --git a/_quarto.yml b/_quarto.yml index ac760ed..30ea912 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -25,6 +25,8 @@ website: href: getting_started.qmd - text: "Enroll for sync updates" href: enroll_sync.qmd + - text: "Start writing" + href: writing_content_courses.qmd - text: "OTTR-fy existing repo" href: ottr-fy.qmd - text: "Giving credits {{< fa award title='An award' >}}" @@ -47,6 +49,8 @@ website: href: more_features_gdoc.qmd - text: "Borrowing chapters {{< fa bookmark title='A bookmark' >}}" href: more_features_borrowing.qmd + - text: "Publishing OTTR courses" + href: publishing.qmd - text: "Troubleshooting {{< fa tools title='tools' >}}" href: faqs.qmd - text: "Contact {{< fa envelope title='An envelope' >}}" diff --git a/publishing.qmd b/publishing.qmd new file mode 100644 index 0000000..6f44fac --- /dev/null +++ b/publishing.qmd @@ -0,0 +1,384 @@ +--- +title: "Publishing OTTR Courses" +format: + html: + toc: true + toc-depth: 4 + toc-location: right +--- + +Below are some examples of courses created using the [OTTR Template](https://github.com/ottrproject/OTTR_Template) and published on three platforms: Bookdown, Leanpub, and Coursera. + +*Introduction to Reproducibility in Cancer Informatics:* + +- [GitHub repository and source code](https://github.com/jhudsl/Reproducibility_in_Cancer_Informatics) + - [Bookdown website](https://jhudatascience.org/Reproducibility_in_Cancer_Informatics/introduction.html) + - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-for-research-leaders) + - [Coursera course](https://www.coursera.org/learn/intro-reproducibility-cancer-informatics) + +*Computing for Cancer Informatics:* + +- [GitHub repository and source code](https://github.com/jhudsl/Computing_for_Cancer_Informatics) + - [Bookdown website](https://jhudatascience.org/Computing_for_Cancer_Informatics/) + - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-computing) + - [Coursera course](https://www.coursera.org/learn/computing-for-cancer-informatics) + + +# Publishing with Bookdown + +To publish your content using Bookdown, utilize GitHub Pages by following the [repository setup instructions](getting_started.html). Note that Bookdown is a prerequisite for Coursera and Leanpub publishing. You must publish with Bookdown before using those platforms. + +As you add or rename chapters, update `_bookdown.yml` accordingly. For example, after adding `03-new_chapter_of_course.Rmd`: + +```{yaml} +book_filename: "Course_Name" +chapter_name: "Chapter " +repo: https://github.com/ottrproject/OTTR_Template/ ##Make sure you update this to your GitHub Repo!! +rmd_files: ["index.Rmd", + "01-intro.Rmd", + "02-chapter_of_course.Rmd", + "03-new_chapter_of_course.Rmd", ## This is the only new line! + "about.Rmd"] +new_session: yes +delete_merged_file: true +language: + ui: + chapter_name: "Chapter " +output_dir: "docs" +``` + +Only a single line changes. Be careful with quotation marks (`""`) and commas (`,`). + +Preview the book by running `bookdown::serve_book()` in the RStudio Console. This generates an `.rds` file you can ignore. The live preview will appear in your RStudio Viewer. + +When a pull request is merged to main, [GitHub Actions](#github-actions) will re-run `bookdown::render_book()` and add the results to `main`. + +# Publishing with Leanpub + +OTTR includes everything needed to publish to [Leanpub](https://leanpub.com/). The [`ottrpal` package](https://github.com/ottrproject/ottrpal) handles converting content into a Leanpub-ready format, storing output in the `manuscript` folder. + +::: {.callout-warning} +Do not manually edit files in the `manuscript` folder. It is auto-generated by `ottrpal` and will be overwritten. +::: + +If you want quizzes and answers hidden, you will need a separate private OTTR_Quizzes repository. [Start with these instructions](publishing.html#quizzes-repository-checklist) before proceeding. + +## Leanpub Rendering + +The `ottrpal` package handles most formatting for links and other elements, as long as you have followed the [image formatting instructions](writing_content_courses.html#set-up-images). + +GitHub Actions will attempt to convert Bookdown to Leanpub by running `ottrpal::bookdown_to_leanpub()` at the top of the repository. + +### Setting up Leanpub-related GitHub Actions + +When ready to publish to Leanpub, enable the following in your [`config_automation.yml`](customize-robots.html): + +- `render-leanpub: yes` +- `check-quizzes: yes` + +You may also configure chapter and quiz ordering. By default, `make-book-txt: TRUE` orders content by filename numbering. Set `make-book-txt: FALSE` if you want to specify ordering manually via a `Book.txt` file. Read more in the [quizzes section](#setting-up-quizzes). + +After updating `config_automation.yml`, file and merge a pull request. Quiz formatting will be checked automatically and reported in a pull request comment. + +File issues with the `ottrpal` package in its [GitHub repository](https://github.com/ottrproject/ottrpal/issues). + +## Hosting your course on Leanpub + +Finalizing a course on Leanpub can be tricky. The [Using Leanpub](https://hutchdatascience.org/Using_Leanpub/index.html) guide provides detailed help. + +1. Create a [Leanpub account](https://leanpub.com/) if you do not have one. + +2. Start a course: + - Click the three-line button at the far right of the top bar. + - Click the **Author** tab, then **Courses**. + - Verify your email address if prompted. + - Click `create a new course`, then **A Course**. + - Provide a title (the Course URL fills automatically). + - Select **Using Git and GitHub**. + - JHU developers: follow [this additional setup document](https://docs.google.com/document/d/18UQicXwf8d25ayKGF2BrinvRgB_R2ToVn5EDOUcxyoc/edit?usp=sharing). + - Press `add to plan`. + +3. Preview a new version: + - Click the three-line menu, then the **Author** tab, then **Courses**. + - Click your course name or icon. + - Click **Preview New Version**, then `Create Preview`. + +If the render fails, it is typically due to a quiz formatting error. Occasional failures may also occur due to sync lag between GitHub and Leanpub — try again if it fails once. + +## Setting up quizzes {#setting-up-quizzes} + +Store quizzes in the `quizzes/` directory. Use the [template quiz](https://github.com/ottrproject/OTTR_Quizzes/blob/main/quizzes/quiz_ch1.md) as a starting point. All quizzes must be written in [Markua format](https://leanpub.com/markua/read#leanpub-auto-quizzes-and-exercises). + +After adding each quiz, add its filename to the `Book.txt` file at the top of the repository (not the one in `manuscript`) in the correct position. For example, with two quizzes interleaved between three chapters: + +``` +01-intro.md +02-chapter_of_course.md +quiz_1.md +03-chapter_of_course.md +quiz_2.md +about.md +``` + +Files listed with a `#` prefix in `Book.txt` are ignored by Leanpub. + +You cannot have two quizzes with the same `quiz_id`. See an [example quiz here](https://github.com/ottrproject/OTTR_Quizzes/blob/main/quizzes/quiz_ch1.md). + +### Leanpub quiz question types + +**Standard multiple choice** — answer choices are not randomized: + +``` +? A question is here +a) A wrong answer +B) A correct answer has a capital letter +c) A wrong answer +d) A wrong answer +``` + +**Choose answers** — randomizes choices using `C)` for correct, `m)` for mandatory incorrect, and `o)` for optional incorrect. The number of answers must be at least equal to the count of correct and mandatory incorrect answers. + +``` +{choose-answers: 4} +? A question is here +C) The correct answer is signified with a capital C +m) A mandatory incorrect answer +m) A mandatory incorrect answer +o) An optional incorrect answer +o) An optional incorrect answer +``` + +Upon merging to `main`, the `check-quizzes.yml` GitHub Action validates quiz formatting and reports errors on the pull request. + +### Leanpub quiz format rules + +- Quizzes start and end with `{quiz}` and `{\quiz}` tags. +- No exclamation points or colons in answers. +- At least one correct answer per question. +- All question and quiz attributes must be recognized by Leanpub. +- All quizzes must be listed in `Book.txt`. +- The `choose-answers` count must be at least as large as the number of mandatory and correct answers. + +## Converting quizzes from Leanpub to Coursera format + +Convert quizzes to a Coursera-uploadable YAML file by running: + +```{r, eval=FALSE} +ottrpal::convert_quizzes() +``` + +Note that images and links are not currently supported by the conversion script and must be added manually. Colons (`:`) are not allowed in prompts or answers. + +[See full Coursera publishing instructions](course_publishing.html#publishing-with-coursera). + +## `_Quizzes` repository checklist + +- [ ] A [`GH_PAT` has been set](https://www.ottrproject.org/getting_started.html#6_Set_up_your_GitHub_personal_access_token) in both the main Template and the `_Quizzes` repository. +- [ ] [Leanpub course has been created](#hosting-your-course-on-leanpub). + - [ ] Writing mode is set to `GitHub` and linked to your main OTTR_Template repository. +- [ ] `_Quizzes` repository is set to `private`. + - [ ] `main` branch protection is configured: + - [ ] `Require pull request reviews before merging` is checked. + - [ ] `Require status checks to pass before merging` is checked. + - [ ] `Require branches to be up to date before merging` is checked. +- [ ] Repository is [enrolled in automatic updates](enroll_sync.html). +- [ ] `Book.txt` is up to date. +- [ ] [`ottrpal::bookdown_to_leanpub()` ran successfully](#leanpub-rendering). + + +# Publishing with Coursera + +Once your content is extensively developed, consider publishing on Coursera. + +::: {.callout-note} +This guide was prepared for [ITN project](https://www.itcrtraining.org/) developers at Johns Hopkins University or other Coursera partner institutions. Coursera's Educator Resource Center is the authoritative source for platform documentation. +::: + +## Setting up your Coursera course + +**If you are from Johns Hopkins:** Follow [this document](https://docs.google.com/document/d/1aZeOSFLkK4hZne4Vb1iaP_0H4zyhIwvbnw9sbdCFq1Y/edit?usp=sharing) and contact Ira Gooding (iragooding@jhu.edu) to create a course shell. + +**If you are not from Johns Hopkins:** Set up your educator profile and course shell through your own institution. + +## Converting your files for Coursera + +GitHub Actions (in `render-all.yml`) renders your course in a Coursera-compatible format — identical to the standard version but without the left-side table of contents. These files are available in the `docs/no_toc` folder. A preview link is posted as a GitHub comment by `render-preview.yml`. + +If quizzes were written in Leanpub format, `pull-request.yml` converts them automatically for Coursera upload. Alternatively, you can write quizzes directly on Coursera's website and download them as YAML for storage in your repository. + +## Navigating to your course on Coursera + +Go to **My Courses** in your Coursera profile. Your course will appear in the list. Click **Go to Course**, then **Edit Course** in the upper right corner. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/profile.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/my-courses.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/edit-course-nav.png) + +Select your version (initially Version 1): + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/versions.png) + +You are now on the Edit content page: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/edit-content.png) + +Each lesson should contain at least one chapter and one quiz. Each module represents approximately one week of learner work — plan one or two lessons per module accordingly. + +Click `+ Add Lesson` to add a new lesson: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-lesson.png) + +### Adding chapters to Coursera + +Chapter URLs follow this pattern, using your GitHub Pages URL with `/no_toc/` inserted before the filename: + +``` +/no_toc/ +``` + +Find your GitHub Pages URL under `Settings` > `Pages`. For example: + +``` +https://ottrproject.org/OTTR_Template/no_toc/introduction.html +``` + +To add a chapter: in a lesson, click `+ More` and choose **Ungraded Plugin**. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-1.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-2.png) + +Click the edit button on the new Ungraded Plugin: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-3.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-4.png) + +Scroll down and click **Edit Configuration**: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-5.png) + +Replace the example URL with your chapter URL: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-6.png) + +Click **Save Configuration**: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/new-add-chapter-7.png) + +Adjust the time estimate for your content. If the URL is correct, a preview of your chapter appears: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-8.png) + +Edit the title if needed, then click **Publish** to save. Coursera will ask you to confirm — click **Publish** again. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-chapter-9.png) + +### Adding quizzes to Coursera + +From the **Edit content** page, click `+ Quiz` on the lesson where you want to add it: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-1.png) + +Click **Edit** on the new quiz: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-2.png) + +To import a converted Leanpub quiz, click **Import Questions** and choose your converted YAML file. (If not yet converted, [see the conversion section](#converting-quizzes-from-leanpub-to-coursera-format).) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-3.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-4.png) + +Click **Upload**: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/add-quiz-5.png) + +If the upload fails, [file an issue](https://github.com/ottrproject/OTTR_Quizzes/issues) with the file and a description of the failure. Note that images, links, and colons in prompts or answers are not supported. + +After a successful upload, click **Continue**. Change the quiz type from `Practice Quiz` to `Graded Quiz` as needed using the dropdown on the left. Update the time estimate as well. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/quiz-settings.png) + +Assign learning objectives by clicking the plus sign under the title, selecting applicable objectives, and clicking **Save**: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/learning-obj-assigned.png) + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/assign-learning-obj.png) + +Edit the title if needed, then click **Publish** to save. + +## Programmed messages + +From **Edit Course**, navigate to `Content` > `Programmed Messages` in the left sidebar. At minimum, add a **Welcome** and a **Completion** message. Click **Preview** then **Publish** to save each. + +**Welcome message template:** + +``` +Welcome to {Course Name} + +We hope this course will {What will they learn?} + +To get the most out of the course {What do you advise?} + +If you ever encounter any problems with the course, have questions or ideas, please let us know using this feedback form. +``` + +**Completion message template:** + +``` +Congratulations and thank you for completing {name of course}! + +We hope this course has {What do you hope they learned}. + +If you have feedback about our course we would greatly appreciate you filling out this form. +``` + +Add a link to your feedback form using the link icon in both messages. + +## Grading formula + +From **Edit Course**, navigate to your version page. Set the percentage each module's assignments contribute to the final grade. + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/coursera_screenshots/grading-formula.png) + +## Content schedule + +Found under the `Content` tab. Assign modules to weeks of your course here. + +## Module descriptions + +Located just before learning objectives when editing content. Descriptions help learners know what to expect from each module. + +## Landing page + +Add a course image and consider including: + +- Estimated workload +- Skills covered +- Recommended background +- What students will learn + +## Multiple reading formats + +Because Coursera uses plug-ins and there are accessibility concerns, add a reading at the very start of your course directing students to alternative formats. Create a reading using the **Add Reading** button (next to **Add Quiz**) and move it to the top of the first module by dragging the three-line icon on the left. + +Title the reading: + +``` +Multiple Lesson Formats +``` + +Paste and modify the following: + +``` +Like many of our other courses, the content of this course is available in multiple formats. +You can also find the lessons for this course at [insert Bookdown link here]. This format might be most appropriate for you if you rely on screen-reader technology. +Our courses are open source, so you can also find all the source material on GitHub by visiting [insert GitHub link here]. +These resources are used throughout this Coursera course in the form of ungraded plug-ins. You are welcome to use those plug-ins here on Coursera or connect to the content in other formats through the links above. Please select the format that most suits your needs. +Note about links in the plug-ins: The plug-ins used throughout the course feature links to other resources. To follow these links, right-click on them and open in a new tab or window. +Regardless of the format you choose for the instructional content, you must take and pass the quizzes here on Coursera if you want to earn a Coursera certificate. +``` + diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd new file mode 100644 index 0000000..156d0f0 --- /dev/null +++ b/writing_content_courses.qmd @@ -0,0 +1,615 @@ +--- +title: "Start writing content" +format: + html: + toc: true +editor_options: + markdown: + wrap: 72 +--- + +```{=html} + +``` + +Now you have a course repository on GitHub and you're ready to start writing content! + +The OTTR content development process revolves around the use of +**pull requests**! Pull requests are a way to set up +**proposed changes** (instead of direct changes) before you publish +them. They enable OTTR to test your proposed changes for +potential issues such as broken URLs or spelling errors. Importantly, pull requests +facilitate discussions with others regarding proposed changes. + + + +::: {.callout-warning} +The live content is automatically created and stored in the `docs` folder. As our writing process guide will inform you, you **should NOT make direct changes to the `docs` folder**. The automation processes will handle the preparation of these files, and you should refrain from making direct changes to them. To learn how to edit your files and write your course, please review the corresponding section in the writing process guide. +::: + +## About OTTR and Pull Requests + +OTTR will not completely break if you don't use pull requests, but you will be missing out on a lot of the main perks of OTTR. OTTR's checks primarily focus on pull requests so you can avoid accidentally making your mistakes in your live courses. + +When you submit a pull request on OTTR it triggers a sequence of automatic checks performed by GitHub Actions. These checks are designed to assist you as you add content to your course. + +These checks will: + +* Check that the all the URLs actually take learners somewhere +* Check that the code is styled using the `styler` package +* Check that the spelling is correct using the `spelling` package +* Create previews of the rendered versions of the course +* Check the formatting of any quizzes (if applicable) + +You can adjust what checks are run by editing the +`config_automation.yml` file. This is further discussed in this section +about [customizing GitHub Actions](./customize-robots.html). + +We have two recommended ways of writing content that is based on your +comfort and interest level in using Git and GitHub. If you are already comfortable with GitHub you can skip these parts. + + + +
**Get started with OTTR entry level -- editing from the browser** If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser. + +You can edit and add content directly in the GitHub website if you +prefer not to learn Git and GitHub (though we highly recommend it, as +knowing how to use Git/GitHub is a useful skill to integrate into your +workflow -- not just for OTTR). + +**1. Create a new branch** + +With GitHub in order to keep your OTTR course preserved content and code +is managed through the use of branches. To explain branches we'll mainly +refer to two branches: your `main` branch: + +![](resources/images/main_branch.png) + +The `main` branch is what your content will be published from and it +will be live to any learners looking at your course. You will want to +keep this `main` branch as preserved and well curated as possible! + +So when you are ready to add more content you will want to have an +isolated copy of your files to work from that keeps your main branch +safe as you work. You can name the branch you work from whatever you +like -- its recommended you name it something related to the changes you +are working on + +![](resources/images/working_branch.png) + +To create a new branch through the GitHub website, you will go to your +main course repository page, click on the branch changing button that +says `main`. + +![](resources/images/branch-button.png) + +Type in a name for your new branch; something that relates to the +changes you are making. For the purposes of this example, we'll call +this new branch, `a-new-branch`. + +![](resources/images/new-branch.png) + +Then click `Create branch: new-changes from main`. + +![](resources/images/new-branch-create.png) + +Congrats! You've made a new branch. GitHub will automatically show you +your new branch's files (which have been copied from the `main`). + +You can tell that you are on the new branch as the left corner branch +tab now says the name of our new branch (`a-new-branch`). + +![](resources/images/new-branch-result.png) + +Now that we have a copy of all the files from the `main` branch, we can +safely work on them in the `a-new-branch` branch. + +![](resources/images/main_branch_safe.png) + +Whenever you are making changes, you'll want to check that you are on +your new branch in order to add any new changes to your pull request, +just look at the left upper corner to make sure! + +Now let's try making some changes. + +**2. Committing changes** + +In your OTTR repository, on your new branch, you can now add/edit/rename +currently existing files while protecting your `main` branch. Adding +changes to a branch is called making `commits`. + +We will describe how to edit existing files below, however, GitHub has +great information about how to create and remove files. Additionally +GitHub is always making changes, so if our instructions seem out of date, +definitely checkout GitHub's current documentation: + +- [Follow GitHub's instructions about managing files through their + website + here](https://docs.github.com/en/repositories/working-with-files/managing-files). + +After every edit you make, scroll down and make sure that you choose +`Commit directly to the new-changes branch.`. This will add your changes +to the pull request and thus allowing for these changes to be run +through the OTTR checks. + +Then click `Commit changes`. You will need to do this after every change +to add them to your branch. + +As an example, we will show a simple change to the file called +`01-intro.Rmd`. Scroll down to the this file and click on this file +name. + +![](resources/images/intro_file.png) + +Now click on the edit button to make a change. Notice that it shows what branch we are working on. + +![](resources/images/edit-button.png) + +Make an edit, such as adding to the introduction like so. + +![](resources/images/first_edit.png) + +You can preview how it looks by pressing the `Preview changes` button. +Red will indicate new deletions and green will indicate new additions. + +![](resources/images/first_edit_preview.png) + +Then write a message about what changes you made and press the +`commit changes` button. + +![](resources/images/first_edit_commit.png) + +Now you are ready to open your pull request. [Jump to section titled 'Open a Pull Request'](#open-a-pull-request) + +
+ +
**Get started with OTTR Advanced -- filing a PR from your computer**: If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts. + +If you have an interest in utilizing GitHub (or already possess knowledge in this area), we suggest engaging with GitHub and Git beyond the GitHub website for creating your pull requests. + +If you are new to Git and GitHub, it is recommended you use a Git client +to help you manage your branches more easily. Install +[GitKraken](https://www.gitkraken.com/) for a handy way to manage your +course locally. These steps shown here will show you the GitKraken way +of handling files. + +If you are not new to GitHub, then we recommend skipping this section +and jumping to the [`Setting Up Images` section](#set-up-images). + +**1. Cloning with Git** + +In the GitHub workflow (excluding the Entry-Level writing method), files exist online (remote) and on your computer (local). + +![](resources/images/remote.png) + +You will need to `clone` the course repository to your own +computer. Having a local copy of the files you are working from makes it +easier to work from. Cloning is just making a local copy on your +computer of the remote version of the project on GitHub. + +![](resources/images/cloning.png) + +To get started, you will need to clone your course's repository that you +created, as you will be using it for the duration of writing your +course. + +To clone a GitHub repository, using GitKraken, first, click +`Clone a repo`. Then, choose where you'd like the repository to be on +your computer using the `Browse` button. You will need to `Copy + Paste` +your new repository's url to where it says `URL`. + +![](resources/images/cloning_2.png) + +Navigate to your repository on GitHub to copy the URL. Copying and +pasting is advisable because any little typo will inhibit cloning. + +Now you are ready to click `Clone the repository`! It will ask you if +you'd like to `Open Now`, click that. + +**2. Create a new branch** + +Handling branches is where you unleash the real benefit of GitHub, but +it can be confusing at first. + +In GitHub, preserving the content and code of your OTTR course is accomplished through the utilization of branches. + +To explain branches we'll mainly refer to two branches: your `main` +branch: + +![](resources/images/main_branch.png) + +The `main` branch is what your content will be published from and it +will be live to any learners looking at your course. You will want to +keep this `main` branch as preserved and well curated as possible! + +So when you are ready to add more content you will want to have an +isolated copy of your files to work from that keeps your main branch +safe as you work. You can name the branch you work from whatever you +like -- its recommended you name it something related to the changes you +are working on + +The best way to get a grasp of what the branches represent is to create +one and start using it. + +![](resources/images/a_new_branch_gitkraken.png) + +In GitKraken we can create a new branch; this will be your working copy. +First, click the `Branch` button. Next, type in a branch name in the box +that the cursor is blinking in. In our example, we are calling it +`a-new-branch`. Now click `Enter`! Now you have a new branch! + +![](resources/images/main_branch_safe.png) + +Now we can add/edit/rename currently existing files in our new branch, +knowing that the content and code in the `main` branch is safe. + + +**3. Committing changes** + +Adding changes to a branch is called making `commits`. To modify any +files in a branch we have to first 1) Make our changes as we normally +would and then 2) Commit those changes. + +To commit changes, begin by editing a file using your preferred text editor. You can simply double-click a file locally to open it. For this example, the specific change you make doesn't matter much; it can be a small modification that you will easily notice later. + +![](resources/images/edit_a_file.png) + +If you've made a change to any file in your repository, it will appear +in GitKraken and you can click on it to see the differences. + +![](resources/images/add_file.png) + +If we want to add these file changes to our current branch, we need to +`commit` them. + +![](resources/images/commit_a_file.png) + +Great! Now the changes you've made have been added to your local branch. + +**4. Pushing changes** + +Note that when you've committed your changes locally (on your computer), those changes +won't be on the online version of your repository. To get them to the +remote GitHub copy (the one on [GitHub](https://github.com/)), we will need to `push` your commits. + +Now that we have changes committed to our branch we are ready to also +add them to the remote GitHub copy! + +![](resources/images/push_changes.png) + +To **push** means to add changes that are on your new branch to the +remote branch (internet version on GitHub). The word **origin** just +refers to where your branch is stored on the internet. Choose your +origin in the dropdown menu and click `Submit`. + +![](resources/images/push_changes_gitkraken.png) + +
+ +
**Open a pull request ** + +After a variable number of commits, your branch, perhaps called +`a-new-branch` or any other new branch you might have made, is a +different version of the original code base that may have a nifty +improvement to it. But our main goal is to add that nifty improvement to +the `main` branch. To start this process of bringing in new changes to +the main curated repository, we will create a **pull request**. + +From GitHub: + +> Pull requests let you tell others about changes you've pushed to a +> GitHub repository. Once a pull request is sent, interested parties can +> review the set of changes, discuss potential modifications, and even +> push follow-up commits if necessary. + +Pull requests are the meat of how code changes and improvements get +reviewed and incorporated! A vast majority of the benefits of +incorporating GitHub into your workflow centers around fully utilizing +the power of pull requests! + +![](resources/images/pull_request.png) + +Now we can open up a pull request if we go to our GitHub repository on +GitHub. You might need to migrate back to the main page for your +repository and can do so by simply clicking on the blue name of your +repository at the top. Then you will see something like this yellow +banner message, where there is a button that says +`Compare & pull request`. + +![](resources/images/open_pr.png) + +
Click here if you don't see the pull request message!!! + +Note that sometimes if you have used the same branch multiple times you +may need some extra steps to create a pull request. This will involve +first clicking on the branch tab (which may have a different number). + +![](resources/images/branch_tab.png) + +Then click on the `New Pull Request` button for the branch you want to +work on. Be careful that is the branch you intend. + +![](resources/images/new_PR_2.png) + +
+ +After you click on `Compare & pull request` you'll be taken to a screen +where you can add information about your changes. After you are done +writing your description, click `Create Pull Request`! (If you don't +have your pull request description *perfect* don't worry about it, you +can always edit it later). + +Congrats! You've just opened a pull request! For every set of changes +you'll make to your course, you will want to follow this similar set of +steps. + +**In summary, here are the steps involved:** + +![](resources/images/summary.png) +
+ +## OTTR Checks on pull requests + +Once your pull request is open, the OTTR GitHub Actions checks will begin. These checks will generate reports as comments on your pull request. + + + +Read these comments to begin addressing the problems with more commits +to your branch. + +You can adjust what checks are run by editing the +`config_automation.yml` file. This is further discussed in this section +about [the GitHub +Actions](https://www.ottrproject.org/customize-robots.html). + +If you need more information on failed GitHub actions you can scroll to +the bottom of your pull request where the status of the checks are shown +and click on `Details` for more information. If you are unsure what the +error message means and have trouble addressing it, please [file an +issue on the OTTR_Template repository to get +help](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=cansavvy&labels=bug&template=course-template-problem-report.md). + +For more on [what to put in a pull request's description, you can read +this +chapter](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review---as-an-author.html). + +For more on [how to review a pull request, see this +chapter](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/engaging-in-code-review---as-a-reviewer.html). + + +::: {.callout-note} +If you encounter situations where a spelling report or URL report doesn't look as expected, you may just need to **refresh the page** or **make another commit** to your pull request. +::: + + + + +
+ +### More resources for learning GitHub + +- [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) +- [Happy Git and GitHub for the useR](https://happygitwithr.com/) +- [Using Version Control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) +- [Using GitHub in a workflow in RStudio](https://hutchdatascience.org/Tools_for_Reproducible_Workflows_in_R/using-github-in-a-workflow.html) +- [Introduction to Git and GitHub](https://www.w3schools.com/git/git_intro.asp?remote=github) +- [GitHub docs about creating a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +- [Making a Pull Request](https://www.atlassian.com/git/tutorials/making-a-pull-request) + +# Adding new chapters + +Adding new chapters to your OTTR course requires some specific steps in +addition to what we've discussed here. + +### Step 1: Add a new chapter Rmd file + +To add a new file, follow the provided instructions, ensuring that the file is named with a .Rmd extension. Additionally, make sure to add the file to your specific new branch: + +- For the `Entry Level`, [read + this to add a new file](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). +- For the `Advanced Level`, you'll create this file locally + using RStudio or a text editor of your choice and follow the steps to add, commit + and push those to your new branch. + + +### Step 2: Add the name of your new chapter to your \_bookdown.yml file + +As you modify the names of the chapters of your course and add more +chapters (using the `.Rmd` files), you need to update the +`_bookdown.yml` file accordingly. + +For example let's say that we added another chapter and named the file +`03-new_chapter_of_course.Rmd`. We would update our `_bookdown.yml` to +look like this: + +``` yaml +book_filename: "Course_Name" +chapter_name: "Chapter " +repo: https://github.com/ottrproject/OTTR_Template/ ##Make sure you update this for your GitHub Repo!! +rmd_files: ["index.Rmd", + "01-intro.Rmd", + "02-chapter_of_course.Rmd", + "03-new_chapter_of_course.Rmd", ##Only this is new! + "about.Rmd"] +new_session: yes +delete_merged_file: true +language: + ui: + chapter_name: "Chapter " +output_dir: "docs" +``` + +::: {.callout-warning} +Pay attention to the slight difference in just one line, specifically the line that reads `03-chapter_of_course.Rmd`. Be cautious regarding the use of quotation marks ("") and commas (,) in the line! +::: + + +### Step 3 Commit the \_bookdown.yml file changes to the current branch + +Follow the steps for how to commit changes and commit the edits to your +`_bookdown.yml` file to your current branch. + + + +### Step 4 Go to your pull request to see how the checks turn out + +Go to your repository and click on the `Pull Request` button in the +navbar. + +
+ +------------------------------------------------------------------------ + +## Set up images {#set-up-images} + +To ensure consistency in style and attributions for graphics and images, and to facilitate future updates, you have the option to store all your images in a central Google Slide document. + +We encourage this strategy for several reasons: + +- OTTR can interact with Google Slides to allow you to get all image + updates of your current Google Slides whenever you re-render the + content (no juggling different file versions of your images). +- Google Slides are easily shareable with your collaborators +- Google Slides is free +- Storing your images on Google slides allows them to be in one + central location and may be helpful for you to re-use the media from + your course in the future +- You can make videos of your slides that can be added to your course using [Loqui](https://loqui.fredhutch.org/). Loqui is an interactive web application designed for automated course creation. Loqui takes as input a Google Slides URL, extracts the speaker notes from the slides, and converts them to a voiceover of the video. Also, it converts the slides to images to serve as the visual component of the video. + +::: {.callout-warning} +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! +::: + + +Each Rmd file with images that is a part of your Bookdown needs to have +the following chunk at the beginning so that images are stored properly for +Leanpub conversion. + + + +If you are unfamiliar with [how R Markdown code chunks work, read +this](https://rmarkdown.rstudio.com/lesson-3.html). + +Next, import the appropriate theme (see [this +video](https://youtu.be/pNbwF263yY8) for assistance): + + + +### Accessibility + +Each slide and image added to the courses should be accessible so every +member of your audience can use your content. + +There are two things to check for each slide: + +- [ ] Each slide is described in the notes of the slide so learners + relying on a screen reader can access the content. See + https://lastcallmedia.com/blog/accessible-comics for more guidance + on this. + +- [ ] The color palette choices of the slide are contrasted in a way + that is friendly to those with color vision deficiencies. You can + check this using [Color Oracle](https://colororacle.org/). + + + +### Adding images and graphics in text + +All images should be included in your Google Slides with the captions we +discussed above. To add images in the text in your Rmd, use the +`ottrpal::include_slide()` within an [R code +chunk](https://bookdown.org/yihui/rmarkdown/r-code.html). + + + +You can obtain the Google Slide URL by clicking on the slide with the +image you want to add and copying the address from the browser search +bar: + +![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/slide_url.png) + +Additionally, include notes (similar to the fig.alt text) for each slide in the Google Slides presentation, describing the content and images of the slide. This will enable accessibility for individuals with visual impairments, as the notes can be converted into audio. + +Please note the following formatting requirements for the fig.alt argument when using `include_slide()`: + +* line breaks are not allowed within the fig.alt text. (If there are no line breaks, the text should appear in blue within the code chunk.) +* If you need to put quotes around a phrase within the fig.alt text, stick with the same type (single or double) as used around the full fig.alt text. + +The code chunk option `echo=FALSE` ensures that the R code is hidden from your course, +while the code chunk option `out.width = "100%"` is used to size the image. We generally +recommend going with larger images. + +*You must define `fig.alt` in the code chunk options/parameters to pass +to `knitr`.* You can adjust the size(fig.hight, fig.width, out.width, +out.height), alignment (fig.align), or caption (fig.cap) of the image +you can use these arguments in the code chunk tag: + + + +Google Slides must be **public**. Share settings must be set to "Anyone +on the internet with this link can view". Note that "Private" is the +default setting when you make a new presentation. + +See [Chapter +2](https://github.com/ottrproject/OTTR_Template/blob/main/02-chapter_of_course.Rmd) +of the template course for examples. + + + +### Adding videos in text + +To add a YouTube video to your Rmd files, use the following instructions: + +To get the appropriate YouTube URL do the following: 1) Click on the +**SHARE** button on the lower right corner of the video on YouTube 2) +Click on the **Embed** option on the far left 3) Copy just the part +after `"src ="` and paste the url into the `knitr::include_url()` +function. + +Again, it is important to use the `echo=FALSE` option so that only the +video is shown and not the code to generate it. + +See [Chapter +2](https://github.com/ottrproject/OTTR_Template/blob/main/02-chapter_of_course.Rmd) +of the template course for examples. + + + +### Adding embedded files to text + +Occasionally, it can be beneficial to embed a website or file directly on a webpage, especially when there is a crucial link that you want learners to access without solely relying on them clicking the link. + +To include such a file or website do the following: + + + +Again you will need to include `echo = FALSE` to ensure that the code to +generate the preview of the website or file is not included in your +course material. + +If you want to include a file that is not hosted online, consider +hosting it on GitHub using the method described for hosting your +Bookdown version of the course. See the [Set up GitHub +pages](https://www.ottrproject.org/getting_started.html#7_Set_up_GitHub_Pages) +section. + +Then you would do the following, where the url is that of your hosted +file: + + + +See [Chapter +2](https://github.com/ottrproject/OTTR_Template/blob/main/02-chapter_of_course.Rmd) +of the template course for examples. From 1c03b6f1b0a2e3bcac94dbd3d2c92d8f85a068ef Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Sat, 4 Apr 2026 15:27:49 -0400 Subject: [PATCH 12/37] update ottr error --- resources/dictionary.txt | 12 ++++++++++++ writing_content_courses.qmd | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/resources/dictionary.txt b/resources/dictionary.txt index 635a59c..267b113 100644 --- a/resources/dictionary.txt +++ b/resources/dictionary.txt @@ -98,3 +98,15 @@ Zapier callout Openscapes quartify +Coursera's +Gooding +img +jpg +Loqui +Markua +navbar +px +src +uploadable +useR +voiceover diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index 156d0f0..b337fea 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -552,7 +552,7 @@ while the code chunk option `out.width = "100%"` is used to size the image. We g recommend going with larger images. *You must define `fig.alt` in the code chunk options/parameters to pass -to `knitr`.* You can adjust the size(fig.hight, fig.width, out.width, +to `knitr`.* You can adjust the size(fig.height, fig.width, out.width, out.height), alignment (fig.align), or caption (fig.cap) of the image you can use these arguments in the code chunk tag: From 7e821a2ff7216f14f68ca92cfa5f1db58e451abd Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 10:37:08 -0400 Subject: [PATCH 13/37] order of pages + consistent case + footer --- _quarto.yml | 7 ++++--- resources/footer.html | 14 ++++++++++++++ 2 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 resources/footer.html diff --git a/_quarto.yml b/_quarto.yml index 30ea912..3c5a63c 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -11,7 +11,7 @@ website: href: index.qmd - text: "Quick Start" menu: - - text: "Getting Started" + - text: "Getting started" href: getting_started.qmd - text: "Next steps" href: next_steps.qmd @@ -23,10 +23,10 @@ website: menu: - text: "Template" href: getting_started.qmd - - text: "Enroll for sync updates" - href: enroll_sync.qmd - text: "Start writing" href: writing_content_courses.qmd + - text: "Enroll for sync updates" + href: enroll_sync.qmd - text: "OTTR-fy existing repo" href: ottr-fy.qmd - text: "Giving credits {{< fa award title='An award' >}}" @@ -64,3 +64,4 @@ format: theme: cosmo css: styles.css toc: true + include-after-body: resources/footer.html diff --git a/resources/footer.html b/resources/footer.html new file mode 100644 index 0000000..4d3d45b --- /dev/null +++ b/resources/footer.html @@ -0,0 +1,14 @@ +
+ +
+ +
+ Your feedback is greatly appreciated! You can fill out this form +
+ or file a GitHub issue. +
+
Otter images by Jimin Hwang. +
+
+
+ From 4bd221c75b67c0f7825d2cf78c704fb59c570d85 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 10:37:24 -0400 Subject: [PATCH 14/37] updating jhudsl repo to ottr --- enroll_sync.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enroll_sync.qmd b/enroll_sync.qmd index 28e4ab5..23b46d1 100644 --- a/enroll_sync.qmd +++ b/enroll_sync.qmd @@ -45,7 +45,7 @@ Use one of these options: | Repository | Issue Links | |:---:|:---| | OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | -| OTTR_Quizzes | [Open an issue](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | +| OTTR_Quizzes | [Open an issue](https://github.com/ottrproject/OTTR_Quizzes/issues) | | OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) |

From 601a4506ba223e08c96e92fa8d1060813413c8b8 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 10:37:35 -0400 Subject: [PATCH 15/37] adding a start writing nav link --- next_steps.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/next_steps.qmd b/next_steps.qmd index 5409ea3..2587972 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -198,4 +198,4 @@ See the [Customization menu](customize-style.qmd) for options including Docker c --- -← [Getting Started](getting_started.qmd)   [Enroll for Sync Updates](enroll_sync.qmd) → +← [Getting Started](getting_started.qmd)   [Start writing!](writing_content_courses.qmd)   [Enroll for Sync Updates](enroll_sync.qmd) → From b7c762f28436b66469cfc5b989faa193c5e17381 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 10:37:46 -0400 Subject: [PATCH 16/37] formatting indentation to be better --- writing_content_courses.qmd | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index b337fea..5fb99a5 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -36,7 +36,7 @@ facilitate discussions with others regarding proposed changes. The live content is automatically created and stored in the `docs` folder. As our writing process guide will inform you, you **should NOT make direct changes to the `docs` folder**. The automation processes will handle the preparation of these files, and you should refrain from making direct changes to them. To learn how to edit your files and write your course, please review the corresponding section in the writing process guide. ::: -## About OTTR and Pull Requests +# About OTTR and Pull Requests OTTR will not completely break if you don't use pull requests, but you will be missing out on a lot of the main perks of OTTR. OTTR's checks primarily focus on pull requests so you can avoid accidentally making your mistakes in your live courses. @@ -357,7 +357,7 @@ steps. ![](resources/images/summary.png) -## OTTR Checks on pull requests +# OTTR Checks on pull requests Once your pull request is open, the OTTR GitHub Actions checks will begin. These checks will generate reports as comments on your pull request. @@ -395,7 +395,7 @@ If you encounter situations where a spelling report or URL report doesn't look a
-### More resources for learning GitHub +## More resources for learning GitHub - [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) - [Happy Git and GitHub for the useR](https://happygitwithr.com/) @@ -410,7 +410,7 @@ If you encounter situations where a spelling report or URL report doesn't look a Adding new chapters to your OTTR course requires some specific steps in addition to what we've discussed here. -### Step 1: Add a new chapter Rmd file +## Step 1: Add a new chapter Rmd file To add a new file, follow the provided instructions, ensuring that the file is named with a .Rmd extension. Additionally, make sure to add the file to your specific new branch: @@ -421,7 +421,7 @@ To add a new file, follow the provided instructions, ensuring that the file is n and push those to your new branch. -### Step 2: Add the name of your new chapter to your \_bookdown.yml file +## Step 2: Add the name of your new chapter to your \_bookdown.yml file As you modify the names of the chapters of your course and add more chapters (using the `.Rmd` files), you need to update the @@ -453,23 +453,21 @@ Pay attention to the slight difference in just one line, specifically the line t ::: -### Step 3 Commit the \_bookdown.yml file changes to the current branch +## Step 3: Commit the \_bookdown.yml file changes to the current branch Follow the steps for how to commit changes and commit the edits to your `_bookdown.yml` file to your current branch. -### Step 4 Go to your pull request to see how the checks turn out +## Step 4: Go to your pull request to see how the checks turn out Go to your repository and click on the `Pull Request` button in the navbar.
------------------------------------------------------------------------- - -## Set up images {#set-up-images} +# Set up images {#set-up-images} To ensure consistency in style and attributions for graphics and images, and to facilitate future updates, you have the option to store all your images in a central Google Slide document. @@ -505,9 +503,7 @@ this](https://rmarkdown.rstudio.com/lesson-3.html). Next, import the appropriate theme (see [this video](https://youtu.be/pNbwF263yY8) for assistance): - - -### Accessibility +# Accessibility Each slide and image added to the courses should be accessible so every member of your audience can use your content. @@ -523,9 +519,9 @@ There are two things to check for each slide: that is friendly to those with color vision deficiencies. You can check this using [Color Oracle](https://colororacle.org/). +# Adding media and embedded files in text - -### Adding images and graphics in text +## Adding images and graphics in text All images should be included in your Google Slides with the captions we discussed above. To add images in the text in your Rmd, use the @@ -568,7 +564,7 @@ of the template course for examples. -### Adding videos in text +## Adding videos in text To add a YouTube video to your Rmd files, use the following instructions: @@ -587,7 +583,7 @@ of the template course for examples. -### Adding embedded files to text +## Adding embedded files to text Occasionally, it can be beneficial to embed a website or file directly on a webpage, especially when there is a crucial link that you want learners to access without solely relying on them clicking the link. From a2b4c6d28d9c9aab61d9173f29619846010d1003 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 10:50:41 -0400 Subject: [PATCH 17/37] adding fhdsl to next steps page --- next_steps.qmd | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/next_steps.qmd b/next_steps.qmd index 2587972..2a7478b 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -7,13 +7,11 @@ Now that you've setup a shell for your OTTR repository, there are some next step ## Necessary Next Steps -### Enroll for sync updates - -The OTTR templates are always a work in progress — new features are added and bugs are smoothed out over time. [Your feedback is greatly appreciated](https://github.com/ottrproject/OTTR_Template/issues/new/choose). When updates are made to non-content files (checks, automation), pull requests are automatically filed to downstream repositories made from the template. +### Enroll for sync updates #### Add `jhudsl-robot` as a collaborator -*You can skip this step if your course is in the `jhudsl` organization.* +*You can skip this step if your course is in the `jhudsl` or `fhdsl` organization.* To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a collaborator with write access: @@ -31,7 +29,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you - [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites - [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes -#### If you are part of the jhudsl GitHub organization +#### If you are part of the `jhudsl` or `fhdsl` GitHub organization 1. Open the relevant sync file above and click the pencil icon to edit. 2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. @@ -41,7 +39,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you 3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. 4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. -#### If you are not part of the jhudsl GitHub organization +#### If you are not part of the `jhudsl` or `fhdsl` GitHub organization Use one of these options: @@ -52,15 +50,14 @@ Use one of these options: | Repository | Issue Links | |:---:|:---| | OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | -| OTTR_Quizzes | [Open an issue](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | +| OTTR_Quizzes | [Open an issue](https://github.com/ottrproject/OTTR_Quizzes/issues) | | OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) |

_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._

- -### Customizing branding and style +#### Customizing branding and style Once your repository is set up, it's worth updating the visual identity of your course or website to reflect your project. For full instructions, see the [Customizing Style page](customize-style.qmd). From 4dbe511a3e0bd07eb36ce0c9b80326bcfd657920 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 6 Apr 2026 11:26:09 -0400 Subject: [PATCH 18/37] adding cheatsheet buttons --- getting_started.qmd | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/getting_started.qmd b/getting_started.qmd index e377f28..315c0f2 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -36,6 +36,12 @@ If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.git **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) + + A Quarto-based course template. Recommended for new projects. #### 1. Create a repository from the template @@ -109,6 +115,12 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto **Template repository:** [ottrproject/OTTR_Template](https://github.com/ottrproject/OTTR_Template) + + An R Markdown / Bookdown-based course template with a table of contents on the side. Supports publishing to Coursera and Leanpub. Best choice when you have existing `.Rmd` files to build on. @@ -212,7 +224,13 @@ _If you have any questions about these updates or files, please tag `@kweav` or **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -A Quarto-based website template. The modern standard — recommended for all new projects. + + +A Quarto-based website template. Recommended for all new projects. #### 1. Create a repository from the template @@ -283,7 +301,13 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto **Template repository:** [ottrproject/OTTR_Template_Website](https://github.com/ottrproject/OTTR_Template_Website) -An R Markdown / Bookdown-based website template with a nav bar on top — like the site you're looking at now. Best choice if you have existing `.Rmd` files to build on. + + +An R Markdown / Bookdown-based website template with a nav bar on top. Best choice if you have existing `.Rmd` files to build on. #### 1. Create a repository from the template From 03996e49ad2d0c71aaaa768f9f36c4e392bc2d5b Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 10:36:50 -0400 Subject: [PATCH 19/37] moving update from #22 --- faqs.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/faqs.qmd b/faqs.qmd index 147dd39..5fa25f6 100644 --- a/faqs.qmd +++ b/faqs.qmd @@ -240,7 +240,7 @@ To fix this, see the [OTTR token cheatsheet](https://www.ottrproject.org/cheatsh ## Contact Info -If you have a question that's not addressed by this website or just wanna chat with us about something else, please email us at itcrtrainingnetwork@gmail.com OR you can [leave a GitHub issue here](https://github.com/ottrproject/OTTR_Template/issues/new) and assign or "at" a team member in the description/a comment (`@carriewright11`, `@kweav`, or `@avahoffman`). +If you have a question that's not addressed by this website or just wanna chat with us about OTTR, please email us at itcrtrainingnetwork@gmail.com OR you can [leave a GitHub issue here](https://github.com/ottrproject/OTTR_Template/issues/new) and assign or "at" a team member in the description/a comment (`@carriewright11`, `@kweav`, or `@avahoffman`). We greatly appreciate any feedback! We are always looking for ways to improve OTTR so more open source courses can be made! From 5176a45c56d536ffcc7e2e16a60dac1682034349 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan <65482193+padmashris@users.noreply.github.com> Date: Tue, 7 Apr 2026 10:38:46 -0400 Subject: [PATCH 20/37] Update enroll_sync.qmd Co-authored-by: Carrie Wright <23014755+carriewright11@users.noreply.github.com> --- enroll_sync.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enroll_sync.qmd b/enroll_sync.qmd index 23b46d1..a76b62e 100644 --- a/enroll_sync.qmd +++ b/enroll_sync.qmd @@ -34,7 +34,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you 3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. 4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. -## If you are not part of the `jhudsl` or `fhdsl` GitHub organization +## If you are **not** part of the `jhudsl` or `fhdsl` GitHub organization Use one of these options: From f448896de4c5574b36c4a08fd9a9381663cd93e4 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 10:55:32 -0400 Subject: [PATCH 21/37] adding enroll sync as child qmd https://github.com/ottrproject/ottr_documentation_dev/pull/26#discussion_r3040417772 --- enroll_sync.qmd | 29 +++++++++++------- next_steps.qmd | 79 +++++++++++-------------------------------------- 2 files changed, 35 insertions(+), 73 deletions(-) diff --git a/enroll_sync.qmd b/enroll_sync.qmd index 23b46d1..527c63a 100644 --- a/enroll_sync.qmd +++ b/enroll_sync.qmd @@ -1,10 +1,12 @@ --- -title: "Enroll for Sync Updates" +toc-depth: 5 --- +## Enroll for Sync Updates + The OTTR templates are always a work in progress. New features are added and bugs are smoothed out over time. [Your feedback is greatly appreciated](https://github.com/ottrproject/OTTR_Template/issues/new/choose). When updates are made to non-content files (checks, automation), pull requests are automatically filed to downstream repositories made from the template. -## Add `jhudsl-robot` as a collaborator +### Add `jhudsl-robot` as a collaborator *You can skip this step if your course is in the `jhudsl` or `fhdsl` organization.* @@ -16,7 +18,7 @@ To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a coll -## Which sync file should you edit? +### Which sync file should you edit? Add your repository name to the `.github/sync.yml` file of the OTTR template you created your repository from: @@ -24,7 +26,18 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you - [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites - [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes -## If you are part of the `jhudsl` or `fhdsl` GitHub organization +### If you are not part of the `jhudsl` or `fhdsl` GitHub organization + +Use one of these options: + +- **Google Form** — submit your organization/username and repo name in the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) and we'll make the edit for you. +- **Open an issue** — use the links in the table below and provide your repo info; we'll update `sync.yml` for you. +- **Fork and PR** — fork the template repo, edit `sync.yml` on a new branch adding your repo name where it says `#NEW REPO HERE#`, commit, and open a pull request. Add a comment tagging `@kweav` so we see it. + +
+ +If you are part of the jhudsl or fhdsl GitHub organization + 1. Open the relevant sync file above and click the pencil icon to edit. 2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. @@ -34,13 +47,7 @@ Add your repository name to the `.github/sync.yml` file of the OTTR template you 3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. 4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. -## If you are not part of the `jhudsl` or `fhdsl` GitHub organization - -Use one of these options: - -- **Google Form** — submit your organization/username and repo name in the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) and we'll make the edit for you. -- **Open an issue** — use the links in the table below and provide your repo info; we'll update `sync.yml` for you. -- **Fork and PR** — fork the template repo, edit `sync.yml` on a new branch adding your repo name where it says `#NEW REPO HERE#`, commit, and open a pull request. Add a comment tagging `@kweav` so we see it. +
| Repository | Issue Links | |:---:|:---| diff --git a/next_steps.qmd b/next_steps.qmd index 2a7478b..24d6557 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -1,63 +1,18 @@ --- title: "Next Steps" -toc-depth: 5 +format: + html: + toc: true + toc-depth: 5 --- Now that you've setup a shell for your OTTR repository, there are some next steps that you **need** to take, and some steps that we **highly recommend**. Additionally, there are further customizations you may want to consider. -## Necessary Next Steps +# Necessary Next Steps -### Enroll for sync updates +{{< include enroll_sync.qmd >}} -#### Add `jhudsl-robot` as a collaborator - -*You can skip this step if your course is in the `jhudsl` or `fhdsl` organization.* - -To enable the full functionality of GitHub Actions, add `jhudsl-robot` as a collaborator with write access: - -1. In your repository, go to **Settings** > **Collaborators & Teams** and click **Add people**. -2. Search for and add `jhudsl-robot`. -3. If prompted, choose the **Write** option, then click **Add jhudsl-robot to this repository**. - - - -#### Which sync file should you edit? - -Add your repository name to the `.github/sync.yml` file of the OTTR template you created your repository from: - -- [OTTR_Template sync file](https://github.com/ottrproject/OTTR_Template/blob/main/.github/sync.yml) — for R Markdown courses -- [OTTR_Template_Website sync file](https://github.com/ottrproject/OTTR_Template_Website/blob/main/.github/sync.yml) — for websites -- [OTTR_Quizzes sync file](https://github.com/ottrproject/OTTR_Quizzes/blob/main/.github/sync.yml) — for quizzes - -#### If you are part of the `jhudsl` or `fhdsl` GitHub organization - -1. Open the relevant sync file above and click the pencil icon to edit. -2. Add your repository name where it says `#NEW REPO HERE#`, indented to match the other entries. - -![](https://raw.githubusercontent.com/ottrproject/OTTR_Template/main/resources/screenshots/edit-sync.yml.png) - -3. Click **Commit changes...**, type `Add new repository to sync` as the commit message, and choose **Create a new branch**. -4. Click **Propose changes**, then open a pull request and request `@kweav` as a reviewer. - -#### If you are not part of the `jhudsl` or `fhdsl` GitHub organization - -Use one of these options: - -- **Google Form** — submit your organization/username and repo name in the [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28) and we'll make the edit for you. -- **Open an issue** — use the links in the table below and provide your repo info; we'll update `sync.yml` for you. -- **Fork and PR** — fork the template repo, edit `sync.yml` on a new branch adding your repo name where it says `#NEW REPO HERE#`, commit, and open a pull request. Add a comment tagging `@kweav` so we see it. - -| Repository | Issue Links | -|:---:|:---| -| OTTR_Template | [General issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=new-course-add-to-sync.md&title=) · [Update repo info in sync](https://github.com/ottrproject/OTTR_Template/issues/new?assignees=kweav&labels=&projects=&template=update-course-info-for-sync.md&title=) | -| OTTR_Quizzes | [Open an issue](https://github.com/ottrproject/OTTR_Quizzes/issues) | -| OTTR_Template_Website | [General issue](https://github.com/ottrproject/OTTR_Template_Website/issues/new/choose) · [Add new repo to sync](https://github.com/ottrproject/OTTR_Template_Website/issues/new?assignees=kweav&labels=&projects=&template=new-website-add-to-sync.md&title=) | - -

-_If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._ -

- -#### Customizing branding and style +## Customizing branding and style Once your repository is set up, it's worth updating the visual identity of your course or website to reflect your project. For full instructions, see the [Customizing Style page](customize-style.qmd). @@ -69,9 +24,9 @@ Once your repository is set up, it's worth updating the visual identity of your - **Logo** — logos in the table of contents sidebar are configured via `_output.yml`. Update the image URL and the link to your GitHub repo. - **Colors** — text colors can be changed by editing `assets/style.css`. Search for `#012d72` (dark blue) or `#68ace5` (light blue) and replace with your preferred hex codes. -## Highly Recommended Next Steps +# Highly Recommended Next Steps -### Clean out template placeholder files +## Clean out template placeholder files The OTTR template ships with example content files to show you the structure. Once you're ready to start writing, replace these with your own content. @@ -88,7 +43,7 @@ The OTTR template ships with example content files to show you the structure. On - `resources/` — contains the spell-check dictionary and screenshot helpers - Configuration files: `_bookdown.yml`, `_output.yml`, `book.bib`, `_quarto.yml` -### Update the README +## Update the README The `README.md` in your repository comes with template placeholder text. Update it to describe what your course or website is about, who it's for, and how to contribute or report issues. A clear README helps collaborators and visitors understand your project at a glance. @@ -98,7 +53,7 @@ At minimum, update: - Any links that point to the template repository (replace with your own repo URL) - Author and contact information -### Add a license +## Add a license Adding a license to your repository clarifies how others can use and share your content. For open educational resources, [Creative Commons Attribution 4.0 (CC BY 4.0)](https://choosealicense.com/licenses/cc-by-4.0/) is a common choice — it allows reuse with attribution. @@ -108,7 +63,7 @@ To add a license on GitHub: 2. Click **Add file** > **Create new file** and name it `LICENSE`. 3. GitHub will offer a license picker — select your preferred license and commit. -### Add your repository link to the sidebar +## Add your repository link to the sidebar Linking your GitHub repository from the sidebar makes it easy for readers to find the source, suggest edits, or file issues. @@ -134,7 +89,7 @@ website: Replace `YOUR-ORG/YOUR-REPO` with your actual organization and repository name. -### Set up a feedback channel +## Set up a feedback channel Making it easy for learners to report problems or leave feedback improves your course over time. Two good approaches: @@ -153,7 +108,7 @@ bookdown::gitbook: Then add a direct link to your form in `index.Rmd` or your course footer. For automated responses, [Zapier](https://zapier.com) can connect Google Form submissions to email notifications, Slack alerts, or GitHub issues. -### Giving credits to contributors +## Giving credits to contributors OTTR courses include a credits table to acknowledge everyone who contributed — instructors, editors, publishers, and template engineers. For full instructions, see the [Giving Credits page](more_features_credits.qmd). @@ -164,7 +119,7 @@ OTTR courses include a credits table to acknowledge everyone who contributed — - **Coursera** — add the credits table URL as an ungraded plugin at the start of your course, right after the introduction. - **Leanpub** — ensure `About.md` is listed in `Book.txt` and it will be included automatically. -### Citing sources +## Citing sources OTTR courses use BibTeX-style references managed through a `book.bib` file. For full instructions, see the [Citing Sources page](more_features_sources.qmd). @@ -175,7 +130,7 @@ OTTR courses use BibTeX-style references managed through a `book.bib` file. For - **References list** — keep `References.Rmd` as the last file in `_bookdown.yml` so the full reference list appears at the end of your course. - **Suppress per-chapter references** by adding `split_bib: false` to `_output.yml`. -### Setting up Google Analytics +## Setting up Google Analytics Adding Google Analytics to your OTTR course or website lets you track how people are finding and using your content. For full setup instructions, see the [Google Analytics Integration page](more_features_ganalytic.qmd). @@ -189,7 +144,7 @@ Adding Google Analytics to your OTTR course or website lets you track how people --- -## Additional Customizations to Consider +# Additional Customizations to Consider See the [Customization menu](customize-style.qmd) for options including Docker configuration, borrowing chapters, Google Docs compatibility, and more. From 2ebca266fdca00926a0e1a455c25ea0b1e0374e5 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 11:08:22 -0400 Subject: [PATCH 22/37] adding back template intro https://github.com/ottrproject/ottr_documentation_dev/pull/26#discussion_r3040443507 --- examples.qmd | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/examples.qmd b/examples.qmd index bc84904..116ebf1 100644 --- a/examples.qmd +++ b/examples.qmd @@ -77,6 +77,13 @@ toc: false Explore courses, websites, and templates built with OTTR. If you've made something with OTTR and would like it featured here, [let us know](contact.qmd). +We are actively working on developing additional versions of our original template to cater to specific needs. These variations can range from technical modifications that simplify the template, to tangential adaptations, or even more complex versions compared to the original OTTR template. + +We also noticed that if specific branding or variations of the original template need to be used many times, it's often easier to create a new template (like the AnVIL and DataTrail templates below). + +If you find yourself making a full set of courses and multiple repositories from OTTR, you may want to make a template from our template (If you need to go this route, we recommend reaching out to the OTTR maintainers by [filing a GitHub issue](https://github.com/ottrproject/OTTR_Template/issues/new/choose) and assigning `@cansavvy` and `@carriewright11`). Also please reach out if you have any other interesting ideas or suggestions! + + ```{=html}
From 54b415189661f272b2c756b6171cc2e66ab0a6ae Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 11:36:47 -0400 Subject: [PATCH 23/37] modifying color instructions based on Katherine's update https://github.com/ottrproject/OTTR_Template/pull/16 --- next_steps.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/next_steps.qmd b/next_steps.qmd index 24d6557..50d7182 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -18,11 +18,11 @@ Once your repository is set up, it's worth updating the visual identity of your **Key things to update:** -- **Title** — set in the YAML header of `index.Rmd` (or `index.qmd` for Quarto). +- **Title** — set in the YAML header of `index.qmd` (or `index.Rmd` for R Markdown). +- **Colors** — color theming is controlled through CSS variables. Default values live in `assets/style_config_default.css`, and course-specific overrides should go in `assets/style_config_custom.css`. To customize branding, update variables such as `--link-color`, `--accent-color`, and `--highlight-color`. You generally should not edit color hex codes directly in `assets/style.css`. - **Style set** — the template defaults to the JHU Data Science Lab style. If you are building an ITN or DataTrail course, copy the relevant files from the `style-sets/` folder to switch styles. - **Favicon** — convert your logo to `.ico` format using [favicon.io](https://favicon.io/favicon-converter/), save it in `assets/`, and reference it in the YAML header. - **Logo** — logos in the table of contents sidebar are configured via `_output.yml`. Update the image URL and the link to your GitHub repo. -- **Colors** — text colors can be changed by editing `assets/style.css`. Search for `#012d72` (dark blue) or `#68ace5` (light blue) and replace with your preferred hex codes. # Highly Recommended Next Steps From c03ebe55519cfb7b0ff9a83cfcd4351175d851f4 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 11:44:48 -0400 Subject: [PATCH 24/37] add quarto example chapter files --- next_steps.qmd | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/next_steps.qmd b/next_steps.qmd index 50d7182..63074a5 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -32,7 +32,9 @@ The OTTR template ships with example content files to show you the structure. On **Safe to delete:** -- Example chapter files (e.g., `01-intro.Rmd`, `02-chapter_of_course.Rmd`, `03-chapter_of_course.Rmd`) +- Example chapter files + - For Quarto: `setup.qmd`, `hosting.qmd`, `editing.qmd`, etc + - For RMarkdown: `01-intro.Rmd`, `02-chapter_of_course.Rmd`, `03-chapter_of_course.Rmd`, etc - `index.Rmd` placeholder text (edit in place rather than deleting) - Any images in `resources/images/` that were part of the example content From 91819319c6adc07b84c9634c6b061a5e5622e21d Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 11:48:03 -0400 Subject: [PATCH 25/37] index file moved to not delete --- next_steps.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/next_steps.qmd b/next_steps.qmd index 63074a5..ed7c1a9 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -35,11 +35,11 @@ The OTTR template ships with example content files to show you the structure. On - Example chapter files - For Quarto: `setup.qmd`, `hosting.qmd`, `editing.qmd`, etc - For RMarkdown: `01-intro.Rmd`, `02-chapter_of_course.Rmd`, `03-chapter_of_course.Rmd`, etc -- `index.Rmd` placeholder text (edit in place rather than deleting) - Any images in `resources/images/` that were part of the example content **Do NOT delete:** +- `index.qmd` or `index.Rmd` - Anything inside `.github/workflows/` — these run all the automated checks and rendering - `assets/` — contains styling files - `resources/` — contains the spell-check dictionary and screenshot helpers From c211a8484af321d5d820d00e167d27db8af276ea Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 11:50:35 -0400 Subject: [PATCH 26/37] minor tweak in next steps removing assets from here since users can delete files they don't need --- next_steps.qmd | 1 - 1 file changed, 1 deletion(-) diff --git a/next_steps.qmd b/next_steps.qmd index ed7c1a9..35bf365 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -41,7 +41,6 @@ The OTTR template ships with example content files to show you the structure. On - `index.qmd` or `index.Rmd` - Anything inside `.github/workflows/` — these run all the automated checks and rendering -- `assets/` — contains styling files - `resources/` — contains the spell-check dictionary and screenshot helpers - Configuration files: `_bookdown.yml`, `_output.yml`, `book.bib`, `_quarto.yml` From 39fe0821cd44c789d2c11ec3eb22f9047a7366cb Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 14:06:11 -0400 Subject: [PATCH 27/37] testing https in ignore url --- resources/ignore-urls.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/resources/ignore-urls.txt b/resources/ignore-urls.txt index c5eec02..8758b74 100644 --- a/resources/ignore-urls.txt +++ b/resources/ignore-urls.txt @@ -1,5 +1,4 @@ https://username.github.io/repository_name/ -${r.url} -getting_started.html -r.url -choose_template.html +https://${r.url} +https://getting_started.html +https://choose_template.html From b8fe529b5cded2213836836e161cefd4cdd1f596 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 14:07:07 -0400 Subject: [PATCH 28/37] Update dictionary.txt --- resources/dictionary.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/resources/dictionary.txt b/resources/dictionary.txt index 267b113..729a9db 100644 --- a/resources/dictionary.txt +++ b/resources/dictionary.txt @@ -110,3 +110,6 @@ src uploadable useR voiceover +qmd +theming + From 2920290b78f629d9a4d0c402caf5aa98d5ad0f8a Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 14:11:47 -0400 Subject: [PATCH 29/37] testing www --- resources/ignore-urls.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/resources/ignore-urls.txt b/resources/ignore-urls.txt index 8758b74..ef0d3bc 100644 --- a/resources/ignore-urls.txt +++ b/resources/ignore-urls.txt @@ -1,4 +1,4 @@ https://username.github.io/repository_name/ -https://${r.url} -https://getting_started.html -https://choose_template.html +www.${r.url} +www.getting_started.html +www.choose_template.html From 7feb49ea4a8494d042a7ce910dbdb29dd787e511 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 7 Apr 2026 14:40:57 -0400 Subject: [PATCH 30/37] upping the URL threshold --- config_automation.yml | 2 +- resources/ignore-urls.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/config_automation.yml b/config_automation.yml index 4b6c5e3..8943eb4 100644 --- a/config_automation.yml +++ b/config_automation.yml @@ -8,7 +8,7 @@ check-quizzes: false quiz_error_min: 0 # Check that urls in the content are not broken url-checker: true -url_error_min: 0 +url_error_min: 4 # Spell check Rmds and quizzes spell-check: true spell_error_min: 0 diff --git a/resources/ignore-urls.txt b/resources/ignore-urls.txt index ef0d3bc..ca82be5 100644 --- a/resources/ignore-urls.txt +++ b/resources/ignore-urls.txt @@ -1,4 +1,4 @@ https://username.github.io/repository_name/ -www.${r.url} -www.getting_started.html -www.choose_template.html +${r.url} +getting_started.html +choose_template.html From cd963415f1cd65ffb1456015120aea50dd808bcd Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 9 Apr 2026 11:59:43 -0400 Subject: [PATCH 31/37] adding Quarto in start writing --- writing_content_courses.qmd | 117 +++++++++++++++++++++--------------- 1 file changed, 70 insertions(+), 47 deletions(-) diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index 5fb99a5..e805d19 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -406,66 +406,89 @@ If you encounter situations where a spelling report or URL report doesn't look a - [Making a Pull Request](https://www.atlassian.com/git/tutorials/making-a-pull-request) # Adding new chapters +Adding new chapters to your OTTR course requires a few specific steps depending on whether you are using Quarto or R Markdown. -Adding new chapters to your OTTR course requires some specific steps in -addition to what we've discussed here. - -## Step 1: Add a new chapter Rmd file - -To add a new file, follow the provided instructions, ensuring that the file is named with a .Rmd extension. Additionally, make sure to add the file to your specific new branch: - -- For the `Entry Level`, [read - this to add a new file](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). -- For the `Advanced Level`, you'll create this file locally - using RStudio or a text editor of your choice and follow the steps to add, commit - and push those to your new branch. - - -## Step 2: Add the name of your new chapter to your \_bookdown.yml file - -As you modify the names of the chapters of your course and add more -chapters (using the `.Rmd` files), you need to update the -`_bookdown.yml` file accordingly. - -For example let's say that we added another chapter and named the file -`03-new_chapter_of_course.Rmd`. We would update our `_bookdown.yml` to -look like this: - -``` yaml -book_filename: "Course_Name" -chapter_name: "Chapter " -repo: https://github.com/ottrproject/OTTR_Template/ ##Make sure you update this for your GitHub Repo!! -rmd_files: ["index.Rmd", - "01-intro.Rmd", - "02-chapter_of_course.Rmd", - "03-new_chapter_of_course.Rmd", ##Only this is new! - "about.Rmd"] -new_session: yes -delete_merged_file: true -language: - ui: - chapter_name: "Chapter " -output_dir: "docs" +## Step 1: Add a new chapter file + +Create a new file on your working branch: + +- **Entry Level (browser):** Follow [GitHub's instructions for adding a file](https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). +- **Advanced Level (local):** Create the file in RStudio or a text editor, then add, commit, and push to your branch. + +::: {.panel-tabset} + +### Quarto + +Name the file with a `.qmd` extension, e.g. `03-new_chapter_of_course.qmd`. + +### R Markdown + +Name the file with a `.Rmd` extension, e.g. `03-new_chapter_of_course.Rmd`. + +::: + +## Step 2: Register the new chapter in your config file + +::: {.panel-tabset} +### Quarto + +Add the new filename to `_quarto.yml` under `chapters:`: + +```yaml +project: + type: book +book: + title: "Course Name" + repo-url: https://github.com/ottrproject/OTTR_Template/ + chapters: + - index.qmd + - 01-intro.qmd + - 02-chapter_of_course.qmd + - 03-new_chapter_of_course.qmd ## Only this is new! + - about.qmd +output-dir: docs ``` ::: {.callout-warning} -Pay attention to the slight difference in just one line, specifically the line that reads `03-chapter_of_course.Rmd`. Be cautious regarding the use of quotation marks ("") and commas (,) in the line! +Be cautious with indentation in `_quarto.yml` — YAML is sensitive to spacing and a misaligned line will break the build. ::: +### R Markdown + +Add the new filename to `_bookdown.yml` under `rmd_files:`: + +```{yaml} +book_filename: "Course_Name" +chapter_name: "Chapter " +repo: https://github.com/ottrproject/OTTR_Template/ +rmd_files: ["index.Rmd", + "01-intro.Rmd", + "02-chapter_of_course.Rmd", + "03-new_chapter_of_course.Rmd", ## Only this is new! + "about.Rmd"] +new_session: yes +delete_merged_file: true +language: + ui: + chapter_name: "Chapter " +output_dir: "docs" +``` + +::: {.callout-warning} +Be cautious with quotation marks (`""`) and commas (`,`) on each line — a small typo here will break the build. +::: -## Step 3: Commit the \_bookdown.yml file changes to the current branch -Follow the steps for how to commit changes and commit the edits to your -`_bookdown.yml` file to your current branch. +::: +## Step 3: Commit your config file changes -## Step 4: Go to your pull request to see how the checks turn out +Commit the updated `_quarto.yml` (Quarto) or `_bookdown.yml` (R Markdown) to your current branch following the same commit steps you used for your chapter file. -Go to your repository and click on the `Pull Request` button in the -navbar. +## Step 4: Check your pull request -
+Go to your repository and click the **Pull Requests** tab to review the automated check results for your new chapter. # Set up images {#set-up-images} From c34379d39fb0804d8db00fe1366d68efd9212ff0 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 9 Apr 2026 14:29:07 -0400 Subject: [PATCH 32/37] attempt to fix ottr error --- writing_content_courses.qmd | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index e805d19..ac836b6 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -434,7 +434,7 @@ Name the file with a `.Rmd` extension, e.g. `03-new_chapter_of_course.Rmd`. Add the new filename to `_quarto.yml` under `chapters:`: -```yaml +```{yaml} project: type: book book: @@ -478,8 +478,6 @@ output_dir: "docs" Be cautious with quotation marks (`""`) and commas (`,`) on each line — a small typo here will break the build. ::: - - ::: ## Step 3: Commit your config file changes From 598589a1e6fe4eb3bf1e3e89ef85c3b6c5013df3 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 9 Apr 2026 14:33:17 -0400 Subject: [PATCH 33/37] another attempt --- writing_content_courses.qmd | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index ac836b6..c6ee0c8 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -434,7 +434,9 @@ Name the file with a `.Rmd` extension, e.g. `03-new_chapter_of_course.Rmd`. Add the new filename to `_quarto.yml` under `chapters:`: -```{yaml} +```{r} +#| eval: false +#| include: true project: type: book book: @@ -457,7 +459,9 @@ Be cautious with indentation in `_quarto.yml` — YAML is sensitive to spacing a Add the new filename to `_bookdown.yml` under `rmd_files:`: -```{yaml} +```{r} +#| eval: false +#| include: true book_filename: "Course_Name" chapter_name: "Chapter " repo: https://github.com/ottrproject/OTTR_Template/ From 6cda504c35f63ed85f484af11408c2c1e8c9f9d2 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 9 Apr 2026 14:34:39 -0400 Subject: [PATCH 34/37] cleaning up steps --- writing_content_courses.qmd | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index c6ee0c8..214f05b 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -432,23 +432,20 @@ Name the file with a `.Rmd` extension, e.g. `03-new_chapter_of_course.Rmd`. ::: {.panel-tabset} ### Quarto -Add the new filename to `_quarto.yml` under `chapters:`: +Add the new filename to `_quarto.yml` under `navbar:`: ```{r} #| eval: false #| include: true -project: - type: book -book: - title: "Course Name" - repo-url: https://github.com/ottrproject/OTTR_Template/ - chapters: - - index.qmd - - 01-intro.qmd - - 02-chapter_of_course.qmd - - 03-new_chapter_of_course.qmd ## Only this is new! - - about.qmd -output-dir: docs +navbar: + left: + - text: "" + href: index.qmd + icon: fa-home + - text: 1. Setup + href: setup.qmd + - text: 2. New Chapter + href: new_chapter.qmd ## new! ``` ::: {.callout-warning} @@ -462,20 +459,12 @@ Add the new filename to `_bookdown.yml` under `rmd_files:`: ```{r} #| eval: false #| include: true -book_filename: "Course_Name" -chapter_name: "Chapter " -repo: https://github.com/ottrproject/OTTR_Template/ + rmd_files: ["index.Rmd", "01-intro.Rmd", "02-chapter_of_course.Rmd", "03-new_chapter_of_course.Rmd", ## Only this is new! "about.Rmd"] -new_session: yes -delete_merged_file: true -language: - ui: - chapter_name: "Chapter " -output_dir: "docs" ``` ::: {.callout-warning} From 737ba33a6295429c854806c40d515d41814e4644 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Fri, 10 Apr 2026 14:41:42 -0400 Subject: [PATCH 35/37] next steps as a gallery --- next_steps.qmd | 387 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 276 insertions(+), 111 deletions(-) diff --git a/next_steps.qmd b/next_steps.qmd index 35bf365..2629c8b 100644 --- a/next_steps.qmd +++ b/next_steps.qmd @@ -6,7 +6,126 @@ format: toc-depth: 5 --- -Now that you've setup a shell for your OTTR repository, there are some next steps that you **need** to take, and some steps that we **highly recommend**. Additionally, there are further customizations you may want to consider. +```{css, echo=FALSE} +.steps-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); + gap: 1.25rem; + margin: 1.5rem 0 2rem 0; +} + +.step-card { + border: 1px solid var(--bs-border-color, #dee2e6); + border-radius: 8px; + padding: 1.25rem 1.5rem 1rem 1.5rem; + background: var(--bs-body-bg, #fff); + display: flex; + flex-direction: column; + gap: 0.5rem; +} + +.step-card h3 { + font-size: 1rem; + font-weight: 600; + margin: 0 0 0.25rem 0; + border: none; + padding: 0; +} + +.step-card p { + font-size: 0.875rem; + color: var(--bs-secondary-color, #6c757d); + margin: 0; + line-height: 1.5; +} + +.step-card details { + margin-top: 0.75rem; + font-size: 0.875rem; +} + +.step-card details summary { + cursor: pointer; + font-weight: 500; + color: var(--bs-link-color, #0d6efd); + list-style: none; + padding: 0.25rem 0; + user-select: none; +} + +.step-card details summary::-webkit-details-marker { + display: none; +} + +.step-card details summary::before { + content: "+ "; + font-weight: 700; +} + +.step-card details[open] summary::before { + content: "- "; +} + +.step-card details .card-detail { + padding: 0.75rem 0 0 0; + border-top: 1px solid var(--bs-border-color, #dee2e6); + margin-top: 0.5rem; + line-height: 1.6; + color: var(--bs-body-color, #212529); +} + +.step-card details .card-detail ul { + padding-left: 1.25rem; + margin: 0.5rem 0; +} + +.step-card details .card-detail li { + margin-bottom: 0.35rem; +} + +.step-card details .card-detail code { + font-size: 0.8rem; +} + +.step-card details .card-detail pre { + font-size: 0.78rem; + background: var(--bs-tertiary-bg, #f8f9fa); + border: 1px solid var(--bs-border-color, #dee2e6); + border-radius: 4px; + padding: 0.75rem; + overflow-x: auto; + white-space: pre; +} +``` + +Now that you've set up a shell for your OTTR repository, there are some next steps that you **need** to take, and some steps that we **highly recommend**. Additionally, there are further customizations you may want to consider. + +```{=html} + +``` + # Necessary Next Steps @@ -20,134 +139,180 @@ Once your repository is set up, it's worth updating the visual identity of your - **Title** — set in the YAML header of `index.qmd` (or `index.Rmd` for R Markdown). - **Colors** — color theming is controlled through CSS variables. Default values live in `assets/style_config_default.css`, and course-specific overrides should go in `assets/style_config_custom.css`. To customize branding, update variables such as `--link-color`, `--accent-color`, and `--highlight-color`. You generally should not edit color hex codes directly in `assets/style.css`. -- **Style set** — the template defaults to the JHU Data Science Lab style. If you are building an ITN or DataTrail course, copy the relevant files from the `style-sets/` folder to switch styles. - **Favicon** — convert your logo to `.ico` format using [favicon.io](https://favicon.io/favicon-converter/), save it in `assets/`, and reference it in the YAML header. - **Logo** — logos in the table of contents sidebar are configured via `_output.yml`. Update the image URL and the link to your GitHub repo. +- **Style set** — the template defaults to the JHU Data Science Lab style. If you are building an ITN or DataTrail course, copy the relevant files from the `style-sets/` folder to switch styles. # Highly Recommended Next Steps -## Clean out template placeholder files - -The OTTR template ships with example content files to show you the structure. Once you're ready to start writing, replace these with your own content. - -**Safe to delete:** - -- Example chapter files - - For Quarto: `setup.qmd`, `hosting.qmd`, `editing.qmd`, etc - - For RMarkdown: `01-intro.Rmd`, `02-chapter_of_course.Rmd`, `03-chapter_of_course.Rmd`, etc -- Any images in `resources/images/` that were part of the example content - -**Do NOT delete:** - -- `index.qmd` or `index.Rmd` -- Anything inside `.github/workflows/` — these run all the automated checks and rendering -- `resources/` — contains the spell-check dictionary and screenshot helpers -- Configuration files: `_bookdown.yml`, `_output.yml`, `book.bib`, `_quarto.yml` - -## Update the README - -The `README.md` in your repository comes with template placeholder text. Update it to describe what your course or website is about, who it's for, and how to contribute or report issues. A clear README helps collaborators and visitors understand your project at a glance. - -At minimum, update: - -- The title and description -- Any links that point to the template repository (replace with your own repo URL) -- Author and contact information - -## Add a license - -Adding a license to your repository clarifies how others can use and share your content. For open educational resources, [Creative Commons Attribution 4.0 (CC BY 4.0)](https://choosealicense.com/licenses/cc-by-4.0/) is a common choice — it allows reuse with attribution. - -To add a license on GitHub: - -1. Go to your repository's main page. -2. Click **Add file** > **Create new file** and name it `LICENSE`. -3. GitHub will offer a license picker — select your preferred license and commit. - -## Add your repository link to the sidebar - -Linking your GitHub repository from the sidebar makes it easy for readers to find the source, suggest edits, or file issues. - -For **R Markdown courses**, update `_output.yml`: - -```yaml -bookdown::gitbook: +Click any card to expand full instructions. + +```{r, echo=FALSE, results='asis'} +cards <- list( + list( + title = "Clean out template placeholder files", + summary = "Remove example content that comes with the template and replace it with your own.", + detail = ' +

Safe to delete:

+
    +
  • Example chapter files +
      +
    • For Quarto: setup.qmd, hosting.qmd, editing.qmd, etc.
      • +
    • For RMarkdown: 01-intro.Rmd, 02-chapter_of_course.Rmd, 03-chapter_of_course.Rmd, etc.
      • +
    +
    • +
  • Any images in resources/images/ that were part of the example content
    • +
+

Do NOT delete:

+
    +
  • index.qmd or index.Rmd
    • +
  • Anything inside .github/workflows/ — these run all the automated checks and rendering
    • +
  • resources/ — contains the spell-check dictionary and screenshot helpers
    • +
  • Configuration files: _bookdown.yml, _output.yml, book.bib, _quarto.yml
    • +
' + ), + list( + title = "Update the README", + summary = "Replace template placeholder text with a description of your course, its audience, and how to contribute.", + detail = ' +

The README.md in your repository comes with template placeholder text. Update it to describe what your course or website is about, who it\'s for, and how to contribute or report issues. A clear README helps collaborators and visitors understand your project at a glance.

+

At minimum, update:

+
    +
  • The title and description
    • +
  • Any links that point to the template repository (replace with your own repo URL)
    • +
  • Author and contact information
    • +
' + ), + list( + title = "Add a license", + summary = "Clarify how others can use and share your content by adding a license file to your repository.", + detail = ' +

Adding a license to your repository clarifies how others can use and share your content. For open educational resources, Creative Commons Attribution 4.0 (CC BY 4.0) is a common choice — it allows reuse with attribution.

+

To add a license on GitHub:

+
    +
  1. Go to your repository\'s main page.
    2. +
  2. Click Add file > Create new file and name it LICENSE.
    3. +
  3. GitHub will offer a license picker — select your preferred license and commit.
    4. +
' + ), + list( + title = "Add your repository link to the sidebar", + summary = "Link your GitHub repository from the course sidebar so readers can find the source, suggest edits, or file issues.", + detail = ' +

For R Markdown courses, update _output.yml:

+
bookdown::gitbook:
   config:
     edit:
-      link: https://github.com/YOUR-ORG/YOUR-REPO/edit/main/%s
-      text: "Suggest an edit"
+      link: https://github.com/YOUR-ORG/YOUR-REPO/
+      text: "GitHub Repository"
     download: no
-    sharing: no
-```
-
-For **Quarto**, update `_quarto.yml`:
-
-```yaml
-website:
-  repo-url: https://github.com/YOUR-ORG/YOUR-REPO
-  repo-actions: [edit, issue]
-```
-
-Replace `YOUR-ORG/YOUR-REPO` with your actual organization and repository name.
-
-## Set up a feedback channel
-
-Making it easy for learners to report problems or leave feedback improves your course over time. Two good approaches:
-
-**GitHub issue templates** — add structured issue forms so readers can report content errors, broken links, or general feedback directly from your repo. You can use [OTTR's example issue templates](https://github.com/ottrproject/OTTR_Template/tree/main/.github/ISSUE_TEMPLATE) as a starting point.
-
-**Google Form link** — for audiences less familiar with GitHub, add a feedback Google Form link to your course. In `_output.yml`, you can surface this in the sharing config:
-
-```yaml
-bookdown::gitbook:
+    sharing: no
+

For Quarto, update _quarto.yml:

+
book:
+    repo-url: https://github.com/YOUR-ORG/YOUR-REPO
+

Replace YOUR-ORG/YOUR-REPO with your actual organization and repository name.

' + ), + list( + title = "Set up a feedback channel", + summary = "Make it easy for learners to report problems or leave feedback to improve your course over time.", + detail = ' +

Two good approaches:

+
+

GitHub issue templates — add structured issue forms so readers can report content errors, broken links, or general feedback directly from your repo. You can use OTTR\'s example issue templates as a starting point.

+
+

Google Form link — for audiences less familiar with GitHub, add a feedback Google Form link to your course. In _output.yml, you can surface this in the sharing config:

+
bookdown::gitbook:
   config:
     sharing:
       facebook: false
       twitter: false
-      all: []
+      all: []
+

Then add a direct link to your form in index.Rmd or your course footer. For automated responses, Zapier can connect Google Form submissions to email notifications, Slack alerts, or GitHub issues.

' + ), + list( + title = "Give credits to contributors", + summary = "Acknowledge everyone who contributed including instructors, editors, publishers, and template engineers.", + detail = ' +

OTTR courses include a credits table to acknowledge everyone who contributed. For full instructions, see the Giving Credits page.

+

Key things to update:

+
    +
  • About.Rmd — already included in the template. Fill in author names for each role, remove inapplicable rows, and make sure role names grammatically match (singular vs. plural).
    • +
  • Required rows — all courses should include rows for Template Publishing Engineers, Publishing Maintenance Engineer, Technical Publishing Stylists, and Package Developers. See the full credits table reference.
    • +
  • Coursera — add the credits table URL as an ungraded plugin at the start of your course, right after the introduction.
    • +
  • Leanpub — ensure About.md is listed in Book.txt and it will be included automatically.
    • +
' + ), + list( + title = "Cite your sources", + summary = "Manage references with a BibTeX file and cite sources inline throughout your course.", + detail = ' +

OTTR courses use BibTeX-style references managed through a book.bib file. For full instructions, see the Citing Sources page.

+
    +
  • Add references to book.bib in alphabetical order. For articles with a DOI, use doi2bib.org or ZoteroBib to generate a BibTeX entry to copy in.
    • +
  • Cite in text using @key (inline) or [@key] (parenthetical). Separate multiple citations with semicolons: [@key-1; @key-2].
    • +
  • References list — keep References.Rmd as the last file in _bookdown.yml so the full reference list appears at the end of your course.
    • +
  • Suppress per-chapter references by adding split_bib: false to _output.yml.
    • +
' + ), + list( + title = "Set up Google Analytics", + summary = "Track how people are finding and using your content with Google Analytics.", + detail = ' +

Adding Google Analytics to your OTTR course or website lets you track how people are finding and using your content. For full setup instructions, see the Google Analytics Integration page.

+
    +
  1. Create a Google Analytics account and set up a new property with a Web data stream for your course URL.
    2. +
  2. Copy the <script> code chunk provided by Google Analytics.
    3. +
  3. Paste it into GA_Script.html in your repository (replacing the placeholder content).
    4. +
  4. Push your changes — the GitHub Action will automatically re-render your course and include the tracking code in every page.
    5. +
  5. Verify in Google Analytics (Reports tab) that traffic is being received.
    6. +
' + ) +) + +card_html <- function(card) { + paste0( + '
', + '

', card$title, '

', + '

', card$summary, '

', + '
Full instructions', + '
', card$detail, '
', + '
', + '
' + ) +} + +cat('
\n') +for (card in cards) { + cat(card_html(card), "\n") +} +cat('
\n') ``` -Then add a direct link to your form in `index.Rmd` or your course footer. For automated responses, [Zapier](https://zapier.com) can connect Google Form submissions to email notifications, Slack alerts, or GitHub issues. - -## Giving credits to contributors - -OTTR courses include a credits table to acknowledge everyone who contributed — instructors, editors, publishers, and template engineers. For full instructions, see the [Giving Credits page](more_features_credits.qmd). - -**Key things to update:** - -- **`About.Rmd`** — already included in the template. Fill in author names for each role, remove inapplicable rows, and make sure role names grammatically match (singular vs. plural). -- **Required rows** — all courses should include rows for Template Publishing Engineers, Publishing Maintenance Engineer, Technical Publishing Stylists, and Package Developers. See the [full credits table reference](https://bit.ly/course-credits-table). -- **Coursera** — add the credits table URL as an ungraded plugin at the start of your course, right after the introduction. -- **Leanpub** — ensure `About.md` is listed in `Book.txt` and it will be included automatically. - -## Citing sources - -OTTR courses use BibTeX-style references managed through a `book.bib` file. For full instructions, see the [Citing Sources page](more_features_sources.qmd). - -**Key things to know:** - -- **Add references** to `book.bib` in alphabetical order. For articles with a DOI, use [doi2bib.org](https://www.doi2bib.org/) or [ZoteroBib](https://zbib.org/) to generate a BibTeX entry to copy in. -- **Cite in text** using `@key` (inline) or `[@key]` (parenthetical). Separate multiple citations with semicolons: `[@key-1; @key-2]`. -- **References list** — keep `References.Rmd` as the last file in `_bookdown.yml` so the full reference list appears at the end of your course. -- **Suppress per-chapter references** by adding `split_bib: false` to `_output.yml`. - -## Setting up Google Analytics - -Adding Google Analytics to your OTTR course or website lets you track how people are finding and using your content. For full setup instructions, see the [Google Analytics Integration page](more_features_ganalytic.qmd). - -**Quick overview:** - -1. Create a [Google Analytics account](https://analytics.google.com/analytics) and set up a new property with a **Web** data stream for your course URL. -2. Copy the `