diff --git a/_quarto.yml b/_quarto.yml index 3c5a63c..0b243bb 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -17,8 +17,6 @@ website: href: next_steps.qmd - text: "Example use cases" href: examples.qmd - - text: "Help me choose my template" - href: choose_template.qmd - text: "Build with OTTR" menu: - text: "Template" @@ -32,15 +30,7 @@ website: - text: "Giving credits {{< fa award title='An award' >}}" href: more_features_credits.qmd - text: "---" - - text: "Customize" - - text: "Style {{< fa palette title='A palette' >}}" - href: customize-style.qmd - - 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: "Highly Recommended Steps" - 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' >}}" @@ -49,8 +39,23 @@ website: href: more_features_gdoc.qmd - text: "Borrowing chapters {{< fa bookmark title='A bookmark' >}}" href: more_features_borrowing.qmd + - text: "" + - text: "---" + - text: "Additional Customizations" + - text: "Style {{< fa palette title='A palette' >}}" + href: customize-style.qmd + - text: "Checks {{< fa robot title='A robot' >}}" + href: customize-robots.qmd + - text: "Docker {{< fa gears title='gears' >}}" + href: customize-docker.qmd - text: "Publishing OTTR courses" - href: publishing.qmd + menu: + - text: "Bookdown" + href: publishing_bookdown.qmd + - text: "Coursera" + href: publishing_coursera.qmd + - text: "Leanpub" + href: publishing_coursera.qmd - text: "Troubleshooting {{< fa tools title='tools' >}}" href: faqs.qmd - text: "Contact {{< fa envelope title='An envelope' >}}" @@ -64,4 +69,8 @@ format: theme: cosmo css: styles.css toc: true + toc-location: left include-after-body: resources/footer.html + page-layout: article + + diff --git a/customize-style.qmd b/customize-style.qmd index 5b249df..1a8e846 100644 --- a/customize-style.qmd +++ b/customize-style.qmd @@ -90,11 +90,45 @@ Thus as example the reference page looks like this: ## Changing course text colors -To modify the colors used for the text, take a look at the `assets/style.css` code. +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`. -If you would like to change the current dark blue color to be a different color, search and replace for `#012d72`. You can find hex color codes at this [website](https://htmlcolorcodes.com/color-picker/) to use as a replacement. +For example, within your `assets/style_config_custom.css` file, you would add: -If you would like to change the current light blue color to be a different color, do the same but search for `#68ace5`. +``` +/* +any variables listed in style_config_default.css can be overridden by giving them a new value in this file +- add additional variable on new lines inside the :root element +- don't forget the semicolon at the end of the line +*/ + +:root { + --link-color: #a1005a; /* deep magenta for links */ + --accent-color: #6e0040; /* dark rose (headings, emphasis) */ + --highlight-color: #e754a6; /* vibrant pink for UI highlights */ + --caption-color: #4a4a4a; /* neutral dark gray */ + --background-color: #ffffff; + --callout-background-color: #f6e9f1; /* soft pink-tinted gray */ + } +``` + +### Accessible Color Palettes + +It’s crucial to ensure that the color palettes you use are accessible to all viewers, including those with color vision deficiencies. Thoughtfully choosing color schemes enhances readability and helps convey information more effectively. This section covers tips for using accessible color palettes and introduces tools like **ColorBuddy**, and **Venngage** for designing visualizations that everyone can interpret. + +#### Recommended Resources + +**1. ColorBuddy** + +Link: + +ColorBuddy is a tool that helps you create and test color palettes for accessibility. It helps you make excellent color palettes for data visualization via a direct manipulation environment that evaluates your color palettes as you go. + + +**2. Venngage Color Accessibility Tool** + +Link: + +Venngage offers a free tool that creates accessible color, ensuring you meet the Web Content Accessibility Guidelines (WCAG) standards.
diff --git a/enroll_sync.qmd b/enroll_sync.qmd index 527c63a..b739faf 100644 --- a/enroll_sync.qmd +++ b/enroll_sync.qmd @@ -2,6 +2,29 @@ toc-depth: 5 --- + +
+ + +
+ ↗ Open in new tab +
+ +
+ +
+ + + Full setup guide with screenshots + + + ## 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. @@ -59,6 +82,8 @@ If you are part of the jhudsl or fhdsl GitHub organiz _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/faqs.qmd b/faqs.qmd index 5fa25f6..0dcb272 100644 --- a/faqs.qmd +++ b/faqs.qmd @@ -238,6 +238,292 @@ To fix this, see the [OTTR token cheatsheet](https://www.ottrproject.org/cheatsh 2) Under **Workflow permissions**, select `Read and write permissions`. 3) Click **Save**, then re-run the failed workflow. +## 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 | + +::: {.callout-warning} +### R Markdown is no longer being actively updated + +Posit has shifted its focus to Quarto as the next-generation publishing system for data science. While OTTR's R Markdown templates remain functional, R Markdown **will not receive new features or improvements going forward**. If you have existing `.Rmd` files, they will continue to work but for any new project, we strongly recommend starting 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 +::: + +### 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. + ## Contact Info 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`). diff --git a/getting_started.qmd b/getting_started.qmd index 315c0f2..a6d7bb3 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -1,440 +1,223 @@ --- title: "Getting Started" toc-depth: 4 ---- - -## Prerequisites for using OTTR - -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. - -Please check out these resources if you are not familiar with R Markdown/Quarto. Note that OTTR is also compatible with regular Markdown websites. - -- 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. - -If you are not familiar with **Git and GitHub**, we recommend going through these chapters from our Reproducibility courses: - -- [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) +page-layout: full +--- -We offer two suggested approaches based on your comfort with Git and GitHub: +:::: {.intro-grid} -- **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. +::: {.intro-prereqs} -If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.gitkraken.com/) as a Git client to facilitate branch management. +## Prerequisites for using OTTR ---- +You do not need to be an expert to get started. A few basics will help: -## Courses - +- **Writing:** basic [Markdown](https://www.markdownguide.org/getting-started/) plus [Quarto](https://quarto.org/docs/get-started/) or [R Markdown](https://rmarkdown.rstudio.com/lesson-1.html), depending on your template. +- **GitHub:** an account and enough comfort to create repositories, update settings, and read GitHub Actions results. +- **Workflow:** use the browser-only entry path if you are new to Git, or install Git/[GitKraken](https://www.gitkraken.com/) for local editing. -### Quarto Courses +::: - +::: {.template-chooser} -**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) +## Choose what you want to build -
- - Cheatsheet +```{=html} +
+ + Courses + Chaptered learning materials with navigation, publishing options, and course-specific setup guides. + + + Websites + Documentation, project sites, and public resources that do not need course-style structure. + + + Dashboards + Metric dashboards for GitHub, analytics, forms, and package stats.
+``` -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. +## Courses -![](resources/screenshots/change_https.png) +::: {.path-header} +**Use this path when:** you are building chaptered learning materials, modules, or a course website. +::: -

-**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) +### Quarto Courses {.toc-anchor-heading} -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). +
+ + Quarto Courses + Best for new course builds + -#### Start writing! +**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -Content is written in `.qmd` files using standard [Quarto syntax](https://quarto.org/docs/authoring/markdown-basics.html). +
+ + +
+ ↗ Open in new tab +
+ +
---- +::: {.template-actions} +[Full setup guide with screenshots](quarto-course.qmd) [Next Steps](next_steps.qmd) → +::: + +
-### R Markdown Courses +### R Markdown Courses {.toc-anchor-heading} - +
+ + R Markdown Courses + Best for `.Rmd` or Bookdown courses + **Template repository:** [ottrproject/OTTR_Template](https://github.com/ottrproject/OTTR_Template) -
- - Cheatsheet - +
+ + +
+ ↗ Open in new tab +
+
-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`._ -

- ---- +::: {.template-actions} +[Full setup guide with screenshots](rmd-course.qmd) [Next Steps](next_steps.qmd) → +::: + +
## Websites -### Quarto Websites +::: {.path-header} +**Use this path when:** you want a project website, documentation site, resource hub, or public-facing guide without course-style chapters. +::: + +### Quarto Websites {.toc-anchor-heading} - +
+ + Quarto Websites + Best for new websites + **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -
- - Cheatsheet - +
+ + +
+ ↗ Open in new tab +
+
-A Quarto-based website template. Recommended for all new projects. +::: {.template-actions} +[Full setup guide with screenshots](quarto-website.qmd) -#### 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) → +::: ---- +
-[Next Steps](next_steps.qmd) → +### R Markdown Websites {.toc-anchor-heading} -### R Markdown Websites +
+ + R Markdown Websites + Best for existing `.Rmd` sites + **Template repository:** [ottrproject/OTTR_Template_Website](https://github.com/ottrproject/OTTR_Template_Website) -
- - Cheatsheet - +
+ + +
+ ↗ Open in new tab +
+
-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. - -![](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`._ -

- ---- +::: {.template-actions} +[Full setup guide with screenshots](rmd-website.qmd) [Next Steps](next_steps.qmd) → +::: + +
## Dashboards ### Metricminer Dashboard +::: {.path-header} +**Use this path when:** you want a dashboard that reports project metrics from GitHub, Google Analytics, Google Forms, CRAN, Calendly, and other sources. + **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 new repository from the [metricminer-dashboard template](https://github.com/ottrproject/metricminer-dashboard). +2. Make the repository public, then enable GitHub Actions **Read and write permissions** and **Allow GitHub Actions to create and approve pull requests**. +3. Add a repository secret named `GH_PAT` using a classic personal access token with `repo` and `workflow` scopes. +4. Add credentials for the metric sources you want to collect from. +5. Deploy from the `main` branch and `/docs` folder in GitHub Pages, then enable HTTPS. -#### 1. Create a repository from the template + +
+ + Dashboard setup notes + Settings, secrets, and first deploy + 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 +After creating your repository, go to **Settings** > **Actions** > **General**. Make sure you have: -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** +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**. +Go to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets** and click **New repository secret**. Add: - **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 @@ -446,10 +229,10 @@ 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). diff --git a/more_features_ganalytic.qmd b/more_features_ganalytic.qmd index 6221bed..38bea35 100644 --- a/more_features_ganalytic.qmd +++ b/more_features_ganalytic.qmd @@ -2,6 +2,27 @@ title: "Google Analytics" --- +
+ + +
+ ↗ Open in new tab +
+ +
+ +
+ + + Full setup guide with screenshots + + # Set Up Google Analytics Follow these steps to enable traffic tracking for your OTTR course or website. @@ -155,7 +176,7 @@ You can verify the Google Analytics code was included by opening any rendered HT | 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 | - +
--- diff --git a/publishing_bookdown.qmd b/publishing_bookdown.qmd new file mode 100644 index 0000000..b265f51 --- /dev/null +++ b/publishing_bookdown.qmd @@ -0,0 +1,49 @@ +--- +title: "Publishing with Bookdown" +format: + html: + toc: true + toc-depth: 4 + toc-location: right +--- + +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`: + +```{r, eval=FALSE} +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`. + +## Examples + +Below are some examples of courses created using the [OTTR Template](https://github.com/ottrproject/OTTR_Template) and published: + +*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) + +*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/) diff --git a/publishing.qmd b/publishing_coursera.qmd similarity index 55% rename from publishing.qmd rename to publishing_coursera.qmd index 6f44fac..fac9099 100644 --- a/publishing.qmd +++ b/publishing_coursera.qmd @@ -1,5 +1,5 @@ --- -title: "Publishing OTTR Courses" +title: "Publishing with Coursera" format: html: toc: true @@ -7,187 +7,6 @@ format: 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} @@ -382,3 +201,16 @@ Note about links in the plug-ins: The plug-ins used throughout the course featur 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. ``` +## Examples + +Below are some examples of courses created using the [OTTR Template](https://github.com/ottrproject/OTTR_Template) and published: + +*Introduction to Reproducibility in Cancer Informatics:* + +- [GitHub repository and source code](https://github.com/jhudsl/Reproducibility_in_Cancer_Informatics) + - [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) + - [Coursera course](https://www.coursera.org/learn/computing-for-cancer-informatics) diff --git a/publishing_leanpub.qmd b/publishing_leanpub.qmd new file mode 100644 index 0000000..721a176 --- /dev/null +++ b/publishing_leanpub.qmd @@ -0,0 +1,151 @@ +--- +title: "Publishing with Leanpub" +format: + html: + toc: true + toc-depth: 4 + toc-location: right +--- + +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). + +## Examples +Below are some examples of courses created using the [OTTR Template](https://github.com/ottrproject/OTTR_Template) and published: + +*Introduction to Reproducibility in Cancer Informatics:* + +- [GitHub repository and source code](https://github.com/jhudsl/Reproducibility_in_Cancer_Informatics) + - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-for-research-leaders) + +*Computing for Cancer Informatics:* + +- [GitHub repository and source code](https://github.com/jhudsl/Computing_for_Cancer_Informatics) + - [Leanpub course](https://leanpub.com/universities/courses/jhu/cancer-informatics-computing) diff --git a/quarto-course.qmd b/quarto-course.qmd new file mode 100644 index 0000000..a9477c1 --- /dev/null +++ b/quarto-course.qmd @@ -0,0 +1,69 @@ +--- +title: "Getting started: Quarto Courses" +--- + + +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) → diff --git a/quarto-website.qmd b/quarto-website.qmd new file mode 100644 index 0000000..d18cb6f --- /dev/null +++ b/quarto-website.qmd @@ -0,0 +1,71 @@ +--- +title: "Getting started: Quarto Websites" +format: html +--- + + +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. + +![](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) → diff --git a/resources/dictionary.txt b/resources/dictionary.txt index 729a9db..2cb76b3 100644 --- a/resources/dictionary.txt +++ b/resources/dictionary.txt @@ -112,4 +112,6 @@ useR voiceover qmd theming - +ColorBuddy +Venngage +WCAG diff --git a/rmd-course.qmd b/rmd-course.qmd new file mode 100644 index 0000000..1bc4f4b --- /dev/null +++ b/rmd-course.qmd @@ -0,0 +1,97 @@ +--- +title: "Getting started: R Markdown Courses" +--- + +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) → diff --git a/rmd-website.qmd b/rmd-website.qmd new file mode 100644 index 0000000..a283191 --- /dev/null +++ b/rmd-website.qmd @@ -0,0 +1,81 @@ +--- +title: "Getting Started: R Markdown Websites" +--- + + +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. + +![](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) → diff --git a/styles.css b/styles.css index 1812c01..89ea638 100644 --- a/styles.css +++ b/styles.css @@ -5,11 +5,20 @@ margin-top: 100px; } +:root { + --ottr-soft: lightblue; + --ottr-accent: #1f2d3d; + --ottr-accent-dark: RoyalBlue; + --ottr-border: #ADD8E6; + --ottr-link: #2a7a9a; + --ottr-text: #1f2d3d; +} + /* add some color - if you want color behind a major point on your website */ .banner_color { - background-color: lightblue; + background-color: var(--ottr-soft); font-weight:bold; } @@ -23,7 +32,7 @@ /* Style buttons - if you want to have a button */ .btn { - background-color: DodgerBlue; + background-color: var(--ottr-accent); border: none; color: white; padding: 8px 20px; @@ -33,7 +42,273 @@ /* Darker background on mouse-over */ .btn:hover { - background-color: RoyalBlue; + background-color: var(--ottr-accent-dark); +} + +/* Indent nested items in the Quarto table of contents. */ +#TOC ul { + margin-left: 0; + padding-left: 0; +} + +#TOC li { + margin-left: 0; +} + +#TOC .nav-link { + padding-left: 0.25rem; +} + +#TOC ul ul { + margin-left: 0.35rem; + padding-left: 0.9rem; + border-left: 1px solid rgba(0, 0, 0, 0.12); +} + +#TOC ul ul .nav-link { + padding-left: 0.35rem; } +#TOC ul ul ul { + margin-left: 0.2rem; + padding-left: 0.85rem; +} + +#TOC ul ul ul .nav-link { + font-size: 0.95em; +} + +/* Top-level chooser for the Getting Started page. */ +.intro-grid { + display: grid; + grid-template-columns: minmax(260px, 0.85fr) minmax(340px, 1.15fr); + gap: 2rem; + align-items: start; + margin: 1.5rem 0 2.75rem; +} + +.intro-prereqs, +.template-chooser { + min-width: 0; +} + +.intro-prereqs h2, +.template-chooser h2 { + margin-top: 0; +} + +.intro-prereqs ul { + padding-left: 1.1rem; +} +.intro-prereqs li { + margin-bottom: 0.55rem; +} + +.chooser-gallery { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 1rem; +} + +.chooser-card { + display: flex; + height: 100%; + min-height: 13rem; + flex-direction: column; + gap: 0.55rem; + padding: 1rem; + color: var(--ottr-text); + text-decoration: none; + background: white; + border: 1px solid var(--ottr-border); + border-radius: 8px; +} + +.chooser-card:hover, +.chooser-card:focus { + color: var(--ottr-text); + text-decoration: none; + background: var(--ottr-soft); + border-color: var(--ottr-accent); +} + +.chooser-kicker { + width: fit-content; + padding: 0.1rem 0.45rem; + color: white; + font-size: 0.8rem; + font-weight: 700; + background: var(--ottr-accent); + border: 1px solid var(--ottr-accent); + border-radius: 999px; +} + +.chooser-title { + color: var(--ottr-text); + font-size: 1.15rem; + font-weight: 700; +} + +.chooser-copy { + font-size: 0.95rem; + line-height: 1.35; +} + +/* Template path sections. */ +.path-header, +.setup-checklist { + margin: 1rem 0 1.25rem; + padding: 1rem 1.25rem; + color: var(--ottr-text); + background: #f8fbfc; + border-left: 5px solid var(--ottr-accent); + border-radius: 8px; +} + +.path-header p:last-child, +.setup-checklist ol:last-child { + margin-bottom: 0; +} + +.setup-checklist li { + margin-bottom: 0.45rem; +} + +h3.toc-anchor-heading { + height: 0; + margin: 0; + overflow: hidden; + scroll-margin-top: 7rem; +} + +h3.toc-anchor-heading .anchorjs-link { + display: none; +} + +.template-choice { + margin: 1rem 0 1.5rem; + border: 1px solid var(--ottr-border); + border-radius: 8px; + overflow: hidden; +} + +.template-choice summary { + display: grid; + grid-template-columns: max-content minmax(10rem, 1fr) max-content; + gap: 0.25rem 0.75rem; + align-items: center; + padding: 0.85rem 1rem; + color: var(--ottr-text); + cursor: pointer; + background: #f8fbfc; +} + +.template-choice summary:hover, +.template-choice summary:focus { + background: var(--ottr-soft); +} + +.template-choice[open] summary { + border-bottom: 1px solid var(--ottr-border); +} + +.template-choice summary::after { + grid-row: span 2; + color: var(--ottr-text); + content: "Show"; + font-size: 0.85rem; + font-weight: 700; +} + +.template-choice[open] summary::after { + content: "Hide"; +} + +.choice-badge { + grid-row: span 2; + width: fit-content; + padding: 0.15rem 0.5rem; + color: white; + font-size: 0.78rem; + font-weight: 700; + background: var(--ottr-accent); + border-radius: 999px; +} + +.choice-title { + color: var(--ottr-text); + font-size: 1.05rem; + font-weight: 700; +} + +.choice-note { + font-size: 0.92rem; +} + +.template-choice > p, +.template-choice > ul, +.template-choice > ol, +.template-choice > div, +.template-choice > .cheatsheet-frame { + margin-right: 1rem; + margin-left: 1rem; +} + +.template-choice > p:first-of-type { + margin-top: 1rem; +} + +.cheatsheet-frame { + margin: 1.25rem 0 1rem; +} + +.cheatsheet-frame iframe { + width: 100%; + height: 2820px; + border: 1.5px solid var(--ottr-border); + border-radius: 8px; +} + +.cheatsheet-link { + margin-top: 0.25rem; + text-align: right; +} + +.cheatsheet-link a { + color: var(--ottr-link); + font-size: 1rem; +} + +.template-actions { + display: flex; + flex-wrap: wrap; + gap: 0.35rem 1rem; + margin-top: 0.75rem; +} + +.template-actions p { + margin: 0; +} + +@media (max-width: 900px) { + .intro-grid { + grid-template-columns: 1fr; + } + + .chooser-gallery { + grid-template-columns: 1fr; + } + + .chooser-card { + min-height: 0; + } + + .template-choice summary { + grid-template-columns: 1fr; + } + + .choice-badge { + grid-row: auto; + } +} diff --git a/writing_content_courses.qmd b/writing_content_courses.qmd index 214f05b..af0bb05 100644 --- a/writing_content_courses.qmd +++ b/writing_content_courses.qmd @@ -408,6 +408,28 @@ If you encounter situations where a spelling report or URL report doesn't look a # 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. + +
+ + +
+ ↗ Open in new tab +
+ +
+ +
+ + + More details + + ## Step 1: Add a new chapter file Create a new file on your working branch: @@ -481,6 +503,8 @@ Commit the updated `_quarto.yml` (Quarto) or `_bookdown.yml` (R Markdown) to you 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. @@ -515,7 +539,8 @@ 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): +video](https://youtu.be/pNbwF263yY8) for assistance). + # Accessibility