+
+### 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 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.
+
+
+
+ Cheatsheet
+
+
+
+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.
+
+
+
+#### 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). 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.
+
+
+
++**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) + +
+
+ Cheatsheet
+
+
+
+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.
+
+
+
+#### 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). 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.
+
+
+
+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
+
+
+
+| 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) + +
+
+ Cheatsheet
+
+
+
+A Quarto-based website template. 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.
+
+
+
+#### 2. Name your repository and fill in a short description
-Example: Provide an example repo
+Enter a name in the **Repository name** field and provide a brief description in the **Description** box.
-## OTTR Quarto Web
+
-Tab Content
+#### 3. Ensure your repository is set to `public`
-Example: Provide an example repo
+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.
-## OTTR Metricminer Dashboard
+#### 4. Click `Create repository from template` to proceed
-Tab Content
+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.
+
+
+
++**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) + +
+
+ Cheatsheet
+
+
+
+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
+
+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.
+
+
+
+#### 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). 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.
+
+
+
++**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. + + + +#### 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..e4f52ca 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,182 @@ 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.
+
+::: {.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
+:::
+
+---
+
+
diff --git a/resources/ignore-urls.txt b/resources/ignore-urls.txt
index d762bdd..dee52a6 100644
--- a/resources/ignore-urls.txt
+++ b/resources/ignore-urls.txt
@@ -1 +1,15 @@
https://username.github.io/repository_name/
+${r.url}
+choose_template.html
+./choose_template.html
+/choose_template.html
+choose_template.html/
+getting_started.html
+customize-style.html
+customize-robots.html
+more_features_ganalytic.qmd
+more_features_sources.qmd
+more_features_credits.qmd
+choose_template.html
+customize-docker.html
+https://github.com/YOUR-ORG/YOUR-REPO
diff --git a/resources/images/02-chapter_of_course_files/figure-docx/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png b/resources/images/02-chapter_of_course_files/figure-docx/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png
new file mode 100644
index 0000000..b865852
Binary files /dev/null and b/resources/images/02-chapter_of_course_files/figure-docx/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png differ
diff --git a/resources/images/02-chapter_of_course_files/figure-docx/unnamed-chunk-4-1.png b/resources/images/02-chapter_of_course_files/figure-docx/unnamed-chunk-4-1.png
new file mode 100644
index 0000000..3864705
Binary files /dev/null and b/resources/images/02-chapter_of_course_files/figure-docx/unnamed-chunk-4-1.png differ
diff --git a/resources/images/02-chapter_of_course_files/figure-html/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png b/resources/images/02-chapter_of_course_files/figure-html/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png
new file mode 100644
index 0000000..b865852
Binary files /dev/null and b/resources/images/02-chapter_of_course_files/figure-html/1YmwKdIy9BeQ3EShgZhvtb3MgR8P6iDX4DfFD65W_gdQ_gcc4fbee202_0_141.png differ
diff --git a/resources/images/02-chapter_of_course_files/figure-html/unnamed-chunk-4-1.png b/resources/images/02-chapter_of_course_files/figure-html/unnamed-chunk-4-1.png
new file mode 100644
index 0000000..be0f5ca
Binary files /dev/null and b/resources/images/02-chapter_of_course_files/figure-html/unnamed-chunk-4-1.png differ
diff --git a/resources/images/03-test_cases_files/figure-html/12DPZgPteQBwgal6kSPP58zhPhjZ7QSPZLe3NkA8M3eo_gc87451c247_0_17.png b/resources/images/03-test_cases_files/figure-html/12DPZgPteQBwgal6kSPP58zhPhjZ7QSPZLe3NkA8M3eo_gc87451c247_0_17.png
new file mode 100644
index 0000000..55b5a3a
Binary files /dev/null and b/resources/images/03-test_cases_files/figure-html/12DPZgPteQBwgal6kSPP58zhPhjZ7QSPZLe3NkA8M3eo_gc87451c247_0_17.png differ
diff --git a/resources/images/04-figures_files/figure-html/unnamed-chunk-3-1.png b/resources/images/04-figures_files/figure-html/unnamed-chunk-3-1.png
new file mode 100644
index 0000000..0f0641a
Binary files /dev/null and b/resources/images/04-figures_files/figure-html/unnamed-chunk-3-1.png differ
diff --git a/resources/images/GA_Create_Property.png b/resources/images/GA_Create_Property.png
index 6fb30fd..15906ab 100644
Binary files a/resources/images/GA_Create_Property.png and b/resources/images/GA_Create_Property.png differ
diff --git a/resources/images/GA_Property_setup.png b/resources/images/GA_Property_setup.png
index 7e879e1..ef838b6 100644
Binary files a/resources/images/GA_Property_setup.png and b/resources/images/GA_Property_setup.png differ
diff --git a/resources/images/GA_property.png b/resources/images/GA_property.png
index 6cd4db3..e130ae9 100644
Binary files a/resources/images/GA_property.png and b/resources/images/GA_property.png differ
diff --git a/resources/images/GA_start.png b/resources/images/GA_start.png
new file mode 100644
index 0000000..3e8f7ee
Binary files /dev/null and b/resources/images/GA_start.png differ
diff --git a/resources/images/GA_stream_link_correct.png b/resources/images/GA_stream_link_correct.png
index 4a70a7d..d8a1c70 100644
Binary files a/resources/images/GA_stream_link_correct.png and b/resources/images/GA_stream_link_correct.png differ
diff --git a/resources/images/GA_web.png b/resources/images/GA_web.png
index 1bba400..4ea957f 100644
Binary files a/resources/images/GA_web.png and b/resources/images/GA_web.png differ
diff --git a/resources/images/Image_res_72.png b/resources/images/Image_res_72.png
new file mode 100644
index 0000000..0bf9187
Binary files /dev/null and b/resources/images/Image_res_72.png differ
diff --git a/resources/images/basic_otter_circle.PNG b/resources/images/basic_otter_circle.PNG
new file mode 100644
index 0000000..1b84381
Binary files /dev/null and b/resources/images/basic_otter_circle.PNG differ
diff --git a/resources/images/basic_otter_sticker_transparent.PNG b/resources/images/basic_otter_sticker_transparent.PNG
new file mode 100644
index 0000000..8633880
Binary files /dev/null and b/resources/images/basic_otter_sticker_transparent.PNG differ
diff --git a/resources/images/itcr_training_network.png b/resources/images/itcr_training_network.png
new file mode 100644
index 0000000..b696478
Binary files /dev/null and b/resources/images/itcr_training_network.png differ
diff --git a/resources/images/logo.png b/resources/images/logo.png
new file mode 100644
index 0000000..0ade934
Binary files /dev/null and b/resources/images/logo.png differ
diff --git a/resources/images/methods_of_writing.jpg b/resources/images/methods_of_writing.jpg
new file mode 100644
index 0000000..b59a5f5
Binary files /dev/null and b/resources/images/methods_of_writing.jpg differ
diff --git a/resources/images/otter.ico b/resources/images/otter.ico
new file mode 100644
index 0000000..073e63b
Binary files /dev/null and b/resources/images/otter.ico differ
diff --git a/resources/images/pull_request_model.jpg b/resources/images/pull_request_model.jpg
new file mode 100644
index 0000000..1f2f4d4
Binary files /dev/null and b/resources/images/pull_request_model.jpg differ
diff --git a/resources/images/tools.png b/resources/images/tools.png
new file mode 100644
index 0000000..0c74d5d
Binary files /dev/null and b/resources/images/tools.png differ
diff --git a/resources/screenshots/GA_Create_Property.png b/resources/screenshots/GA_Create_Property.png
new file mode 100644
index 0000000..6fb30fd
Binary files /dev/null and b/resources/screenshots/GA_Create_Property.png differ
diff --git a/resources/screenshots/GA_ID.png b/resources/screenshots/GA_ID.png
new file mode 100644
index 0000000..24f98af
Binary files /dev/null and b/resources/screenshots/GA_ID.png differ
diff --git a/resources/screenshots/GA_Property_setup.png b/resources/screenshots/GA_Property_setup.png
new file mode 100644
index 0000000..7e879e1
Binary files /dev/null and b/resources/screenshots/GA_Property_setup.png differ
diff --git a/resources/screenshots/GA_account.png b/resources/screenshots/GA_account.png
new file mode 100644
index 0000000..4dcc02b
Binary files /dev/null and b/resources/screenshots/GA_account.png differ
diff --git a/resources/screenshots/GA_admin.png b/resources/screenshots/GA_admin.png
new file mode 100644
index 0000000..482a34a
Binary files /dev/null and b/resources/screenshots/GA_admin.png differ
diff --git a/resources/screenshots/GA_check.png b/resources/screenshots/GA_check.png
new file mode 100644
index 0000000..a700d23
Binary files /dev/null and b/resources/screenshots/GA_check.png differ
diff --git a/resources/screenshots/GA_property.png b/resources/screenshots/GA_property.png
new file mode 100644
index 0000000..6cd4db3
Binary files /dev/null and b/resources/screenshots/GA_property.png differ
diff --git a/resources/screenshots/GA_reports.png b/resources/screenshots/GA_reports.png
new file mode 100644
index 0000000..fb10a03
Binary files /dev/null and b/resources/screenshots/GA_reports.png differ
diff --git a/resources/screenshots/GA_stream_link.png b/resources/screenshots/GA_stream_link.png
new file mode 100644
index 0000000..96e99a5
Binary files /dev/null and b/resources/screenshots/GA_stream_link.png differ
diff --git a/resources/screenshots/GA_stream_link_correct.png b/resources/screenshots/GA_stream_link_correct.png
new file mode 100644
index 0000000..4a70a7d
Binary files /dev/null and b/resources/screenshots/GA_stream_link_correct.png differ
diff --git a/resources/screenshots/GA_terms.png b/resources/screenshots/GA_terms.png
new file mode 100644
index 0000000..47c125d
Binary files /dev/null and b/resources/screenshots/GA_terms.png differ
diff --git a/resources/screenshots/GA_web.png b/resources/screenshots/GA_web.png
new file mode 100644
index 0000000..1bba400
Binary files /dev/null and b/resources/screenshots/GA_web.png differ
diff --git a/resources/screenshots/GHASetUp.png b/resources/screenshots/GHASetUp.png
new file mode 100644
index 0000000..ea86399
Binary files /dev/null and b/resources/screenshots/GHASetUp.png differ
diff --git a/resources/screenshots/OTTR_Robot_Image.png b/resources/screenshots/OTTR_Robot_Image.png
new file mode 100644
index 0000000..0295d45
Binary files /dev/null and b/resources/screenshots/OTTR_Robot_Image.png differ
diff --git a/resources/screenshots/add-jhudsl-robot.png b/resources/screenshots/add-jhudsl-robot.png
new file mode 100644
index 0000000..e2bf803
Binary files /dev/null and b/resources/screenshots/add-jhudsl-robot.png differ
diff --git a/resources/screenshots/add-repo-sync.png b/resources/screenshots/add-repo-sync.png
new file mode 100644
index 0000000..df5c877
Binary files /dev/null and b/resources/screenshots/add-repo-sync.png differ
diff --git a/resources/screenshots/automatic_checks.png b/resources/screenshots/automatic_checks.png
new file mode 100644
index 0000000..e91952f
Binary files /dev/null and b/resources/screenshots/automatic_checks.png differ
diff --git a/resources/screenshots/branch_settings.png b/resources/screenshots/branch_settings.png
new file mode 100644
index 0000000..1aa3aa5
Binary files /dev/null and b/resources/screenshots/branch_settings.png differ
diff --git a/resources/screenshots/branches.png b/resources/screenshots/branches.png
new file mode 100644
index 0000000..de79550
Binary files /dev/null and b/resources/screenshots/branches.png differ
diff --git a/resources/screenshots/change_https.png b/resources/screenshots/change_https.png
new file mode 100644
index 0000000..3891b0c
Binary files /dev/null and b/resources/screenshots/change_https.png differ
diff --git a/resources/screenshots/change_pages_settings.png b/resources/screenshots/change_pages_settings.png
new file mode 100644
index 0000000..fe0f29e
Binary files /dev/null and b/resources/screenshots/change_pages_settings.png differ
diff --git a/resources/screenshots/check-comments.png b/resources/screenshots/check-comments.png
new file mode 100644
index 0000000..e786593
Binary files /dev/null and b/resources/screenshots/check-comments.png differ
diff --git a/resources/screenshots/check_results.png b/resources/screenshots/check_results.png
new file mode 100644
index 0000000..7855aac
Binary files /dev/null and b/resources/screenshots/check_results.png differ
diff --git a/resources/screenshots/check_results_pass.png b/resources/screenshots/check_results_pass.png
new file mode 100644
index 0000000..4838cb0
Binary files /dev/null and b/resources/screenshots/check_results_pass.png differ
diff --git a/resources/screenshots/clone.png b/resources/screenshots/clone.png
new file mode 100644
index 0000000..42d639b
Binary files /dev/null and b/resources/screenshots/clone.png differ
diff --git a/resources/screenshots/creating_new_course_repo.png b/resources/screenshots/creating_new_course_repo.png
new file mode 100644
index 0000000..61eaa71
Binary files /dev/null and b/resources/screenshots/creating_new_course_repo.png differ
diff --git a/resources/screenshots/edit-sync.yml.png b/resources/screenshots/edit-sync.yml.png
new file mode 100644
index 0000000..1cdb50c
Binary files /dev/null and b/resources/screenshots/edit-sync.yml.png differ
diff --git a/resources/screenshots/example_credits.png b/resources/screenshots/example_credits.png
new file mode 100644
index 0000000..7d4d8b3
Binary files /dev/null and b/resources/screenshots/example_credits.png differ
diff --git a/resources/screenshots/file_pane.png b/resources/screenshots/file_pane.png
new file mode 100644
index 0000000..feae5d8
Binary files /dev/null and b/resources/screenshots/file_pane.png differ
diff --git a/resources/screenshots/gha-actions-error.png b/resources/screenshots/gha-actions-error.png
new file mode 100644
index 0000000..5f0e20a
Binary files /dev/null and b/resources/screenshots/gha-actions-error.png differ
diff --git a/resources/screenshots/gha-checks.png b/resources/screenshots/gha-checks.png
new file mode 100644
index 0000000..3e965c3
Binary files /dev/null and b/resources/screenshots/gha-checks.png differ
diff --git a/resources/screenshots/gha-preview-comment.png b/resources/screenshots/gha-preview-comment.png
new file mode 100644
index 0000000..29ecc60
Binary files /dev/null and b/resources/screenshots/gha-preview-comment.png differ
diff --git a/resources/screenshots/git-secrets.png b/resources/screenshots/git-secrets.png
new file mode 100644
index 0000000..fb541d4
Binary files /dev/null and b/resources/screenshots/git-secrets.png differ
diff --git a/resources/screenshots/guide_issues.png b/resources/screenshots/guide_issues.png
new file mode 100644
index 0000000..b56a6be
Binary files /dev/null and b/resources/screenshots/guide_issues.png differ
diff --git a/resources/screenshots/guides_issues.png b/resources/screenshots/guides_issues.png
new file mode 100644
index 0000000..00f0153
Binary files /dev/null and b/resources/screenshots/guides_issues.png differ
diff --git a/resources/screenshots/guides_issues_2.png b/resources/screenshots/guides_issues_2.png
new file mode 100644
index 0000000..1a87007
Binary files /dev/null and b/resources/screenshots/guides_issues_2.png differ
diff --git a/resources/screenshots/guides_issues_3.png b/resources/screenshots/guides_issues_3.png
new file mode 100644
index 0000000..3b32c1a
Binary files /dev/null and b/resources/screenshots/guides_issues_3.png differ
diff --git a/resources/screenshots/guides_issues_4.png b/resources/screenshots/guides_issues_4.png
new file mode 100644
index 0000000..388b3ca
Binary files /dev/null and b/resources/screenshots/guides_issues_4.png differ
diff --git a/resources/screenshots/issue_enroll.png b/resources/screenshots/issue_enroll.png
new file mode 100644
index 0000000..fcf57c5
Binary files /dev/null and b/resources/screenshots/issue_enroll.png differ
diff --git a/resources/screenshots/main.png b/resources/screenshots/main.png
new file mode 100644
index 0000000..5cfd534
Binary files /dev/null and b/resources/screenshots/main.png differ
diff --git a/resources/screenshots/messages.png b/resources/screenshots/messages.png
new file mode 100644
index 0000000..0b21429
Binary files /dev/null and b/resources/screenshots/messages.png differ
diff --git a/resources/screenshots/new_project.png b/resources/screenshots/new_project.png
new file mode 100644
index 0000000..a5f6c72
Binary files /dev/null and b/resources/screenshots/new_project.png differ
diff --git a/resources/screenshots/numbering_bookdown.png b/resources/screenshots/numbering_bookdown.png
new file mode 100644
index 0000000..b638f6c
Binary files /dev/null and b/resources/screenshots/numbering_bookdown.png differ
diff --git a/resources/screenshots/numbering_leanpub.png b/resources/screenshots/numbering_leanpub.png
new file mode 100644
index 0000000..42fa473
Binary files /dev/null and b/resources/screenshots/numbering_leanpub.png differ
diff --git a/resources/screenshots/output_file_with_GA.png b/resources/screenshots/output_file_with_GA.png
new file mode 100644
index 0000000..feed915
Binary files /dev/null and b/resources/screenshots/output_file_with_GA.png differ
diff --git a/resources/screenshots/pages_settings.png b/resources/screenshots/pages_settings.png
new file mode 100644
index 0000000..4ef82e5
Binary files /dev/null and b/resources/screenshots/pages_settings.png differ
diff --git a/resources/screenshots/pr-prompt.png b/resources/screenshots/pr-prompt.png
new file mode 100644
index 0000000..88ba468
Binary files /dev/null and b/resources/screenshots/pr-prompt.png differ
diff --git a/resources/screenshots/preview_comment.png b/resources/screenshots/preview_comment.png
new file mode 100644
index 0000000..da7c759
Binary files /dev/null and b/resources/screenshots/preview_comment.png differ
diff --git a/resources/screenshots/project_directory.png b/resources/screenshots/project_directory.png
new file mode 100644
index 0000000..4a52269
Binary files /dev/null and b/resources/screenshots/project_directory.png differ
diff --git a/resources/screenshots/project_type.png b/resources/screenshots/project_type.png
new file mode 100644
index 0000000..78c3f1f
Binary files /dev/null and b/resources/screenshots/project_type.png differ
diff --git a/resources/screenshots/pull_request.png b/resources/screenshots/pull_request.png
new file mode 100644
index 0000000..69c96ad
Binary files /dev/null and b/resources/screenshots/pull_request.png differ
diff --git a/resources/screenshots/pull_request_2.png b/resources/screenshots/pull_request_2.png
new file mode 100644
index 0000000..552a8d1
Binary files /dev/null and b/resources/screenshots/pull_request_2.png differ
diff --git a/resources/screenshots/pull_request_3.png b/resources/screenshots/pull_request_3.png
new file mode 100644
index 0000000..7481623
Binary files /dev/null and b/resources/screenshots/pull_request_3.png differ
diff --git a/resources/screenshots/question_example.png b/resources/screenshots/question_example.png
new file mode 100644
index 0000000..9c4696b
Binary files /dev/null and b/resources/screenshots/question_example.png differ
diff --git a/resources/screenshots/request-reviewer.png b/resources/screenshots/request-reviewer.png
new file mode 100644
index 0000000..b8a4cf2
Binary files /dev/null and b/resources/screenshots/request-reviewer.png differ
diff --git a/resources/screenshots/select_directory.png b/resources/screenshots/select_directory.png
new file mode 100644
index 0000000..e9638b5
Binary files /dev/null and b/resources/screenshots/select_directory.png differ
diff --git a/resources/screenshots/slide_url.png b/resources/screenshots/slide_url.png
new file mode 100644
index 0000000..28734b1
Binary files /dev/null and b/resources/screenshots/slide_url.png differ
diff --git a/resources/screenshots/spell_check_comment.png b/resources/screenshots/spell_check_comment.png
new file mode 100644
index 0000000..58161bf
Binary files /dev/null and b/resources/screenshots/spell_check_comment.png differ
diff --git a/resources/screenshots/spell_check_fails.png b/resources/screenshots/spell_check_fails.png
new file mode 100644
index 0000000..a55628b
Binary files /dev/null and b/resources/screenshots/spell_check_fails.png differ
diff --git a/resources/screenshots/template_button.png b/resources/screenshots/template_button.png
new file mode 100644
index 0000000..2dd94b6
Binary files /dev/null and b/resources/screenshots/template_button.png differ
diff --git a/resources/screenshots/templates_to_edit.png b/resources/screenshots/templates_to_edit.png
new file mode 100644
index 0000000..dd8e7ed
Binary files /dev/null and b/resources/screenshots/templates_to_edit.png differ
diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd
new file mode 100644
index 0000000..214f05b
--- /dev/null
+++ b/writing_content_courses.qmd
@@ -0,0 +1,625 @@
+---
+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: + + + +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 + + + +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`. + + + +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`. + + + +Then click `Create branch: new-changes from main`. + + + +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`). + + + +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. + + + +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. + + + +Now click on the edit button to make a change. Notice that it shows what branch we are working on. + + + +Make an edit, such as adding to the introduction like so. + + + +You can preview how it looks by pressing the `Preview changes` button. +Red will indicate new deletions and green will indicate new additions. + + + +Then write a message about what changes you made and press the +`commit changes` button. + + + +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). + + + +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. + + + +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`. + + + +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: + + + +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. + + + +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! + + + +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. + + + +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. + + + +If we want to add these file changes to our current branch, we need to +`commit` them. + + + +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! + + + +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`. + + + +**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! + + + +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`. + + + +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). + + + +Then click on the `New Pull Request` button for the branch you want to +work on. Be careful that is the branch you intend. + + + +
+
+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 a few specific steps depending on whether you are using Quarto or R Markdown. + +## 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 `navbar:`: + +```{r} +#| eval: false +#| include: true +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} +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:`: + +```{r} +#| eval: false +#| include: true + +rmd_files: ["index.Rmd", + "01-intro.Rmd", + "02-chapter_of_course.Rmd", + "03-new_chapter_of_course.Rmd", ## Only this is new! + "about.Rmd"] +``` + +::: {.callout-warning} +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 + +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. + +## 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} + +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 media and embedded files 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
+`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:
+
+
+
+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.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:
+
+
+
+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.