From 569335f596fae8df126a169e8889f3d0873bb0b4 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Tue, 14 Apr 2026 21:56:28 -0400 Subject: [PATCH 01/14] update navbar also added "help me choose" as a subsection inside troubleshooting --- _quarto.yml | 24 +++-- faqs.qmd | 286 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 299 insertions(+), 11 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index 3c5a63c..8879dfe 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,20 @@ 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 + - text: "Cheatsheets" + href: https://www.ottrproject.org/cheatsheets/#ottr + target: _blank - text: "Troubleshooting {{< fa tools title='tools' >}}" href: faqs.qmd - text: "Contact {{< fa envelope title='An envelope' >}}" 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`). From 9f2dbd3ba9da008d46938c97053bd2811639c2f3 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Mon, 20 Apr 2026 13:56:04 -0400 Subject: [PATCH 02/14] update steps to change colors --- customize-style.qmd | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/customize-style.qmd b/customize-style.qmd index 5b249df..1c8d238 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`. + +For example, within your `assets/style_config_custom.css` file, you would add: + +```{css} +/* +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** -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. +Link: -If you would like to change the current light blue color to be a different color, do the same but search for `#68ace5`. +Venngage offers a free tool that creates accesible color, ensuring you meet the Web Content Accessibility Guidelines (WCAG) standards.
From 04b897f292568153332c37f9ea9fec55468c17b3 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 22 Apr 2026 10:40:43 -0400 Subject: [PATCH 03/14] publishing dropdown --- _quarto.yml | 11 +- publishing_bookdown.qmd | 49 ++++++ publishing.qmd => publishing_coursera.qmd | 196 ++-------------------- publishing_leanpub.qmd | 151 +++++++++++++++++ 4 files changed, 221 insertions(+), 186 deletions(-) create mode 100644 publishing_bookdown.qmd rename publishing.qmd => publishing_coursera.qmd (55%) create mode 100644 publishing_leanpub.qmd diff --git a/_quarto.yml b/_quarto.yml index 8879dfe..bae00da 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -49,10 +49,13 @@ website: - text: "Docker {{< fa gears title='gears' >}}" href: customize-docker.qmd - text: "Publishing OTTR courses" - href: publishing.qmd - - text: "Cheatsheets" - href: https://www.ottrproject.org/cheatsheets/#ottr - target: _blank + 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' >}}" 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) From a490b5f724aedc3c4d56e7e4eabe9549204c8e04 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 22 Apr 2026 10:42:57 -0400 Subject: [PATCH 04/14] fix spelling errors --- customize-style.qmd | 2 +- resources/dictionary.txt | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/customize-style.qmd b/customize-style.qmd index 1c8d238..1a61b6f 100644 --- a/customize-style.qmd +++ b/customize-style.qmd @@ -128,7 +128,7 @@ ColorBuddy is a tool that helps you create and test color palettes for accessibi Link: -Venngage offers a free tool that creates accesible color, ensuring you meet the Web Content Accessibility Guidelines (WCAG) standards. +Venngage offers a free tool that creates accessible color, ensuring you meet the Web Content Accessibility Guidelines (WCAG) standards.
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 From 281846839509ead6b735b1868658f6b93a88bbaf Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 22 Apr 2026 18:07:25 -0400 Subject: [PATCH 05/14] flipping cheatsheet format for getting started --- getting_started.qmd | 106 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 87 insertions(+), 19 deletions(-) diff --git a/getting_started.qmd b/getting_started.qmd index 315c0f2..eb020bf 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -25,8 +25,6 @@ We offer two suggested approaches based on your comfort with Git and GitHub: If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.gitkraken.com/) as a Git client to facilitate branch management. ---- - ## Courses @@ -36,12 +34,28 @@ If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.git **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -
- - Cheatsheet - +
+ + + +
+
+ + + Full setup guide with screenshots + + + A Quarto-based course template. Recommended for new projects. #### 1. Create a repository from the template @@ -105,22 +119,39 @@ Add `jhudsl-robot` as a collaborator with write access (**Settings** > **Collabo 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 - + +
+ + + +
+
+ + + Full setup guide with screenshots + + An R Markdown / Bookdown-based course template with a table of contents on the side. Supports publishing to Coursera and Leanpub. Best choice when you have existing `.Rmd` files to build on. @@ -212,6 +243,8 @@ If you're **not** a member of the jhudsl GitHub organization, you can: _If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._

+
+ --- [Next Steps](next_steps.qmd) → @@ -224,12 +257,28 @@ _If you have any questions about these updates or files, please tag `@kweav` or **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -
- - Cheatsheet - + +
+ + + +
+
+ + + Full setup guide with screenshots + + A Quarto-based website template. Recommended for all new projects. #### 1. Create a repository from the template @@ -293,6 +342,8 @@ Add `jhudsl-robot` as a collaborator with write access (**Settings** > **Collabo Content is written in `.qmd` files using standard [Quarto syntax](https://quarto.org/docs/authoring/markdown-basics.html). +
+ --- [Next Steps](next_steps.qmd) → @@ -301,12 +352,27 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto **Template repository:** [ottrproject/OTTR_Template_Website](https://github.com/ottrproject/OTTR_Template_Website) -
- - Cheatsheet - +
+ + + +
+
+ + + Full setup guide with screenshots + + 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 @@ -381,6 +447,8 @@ If you're **not** a member of the jhudsl GitHub organization, you can: _If you have any questions about these updates or files, please tag `@kweav` or `@carriewright11`._

+
+ --- [Next Steps](next_steps.qmd) → From f3add4d2c0f14f213cb44a09956f8c6e649622f7 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Wed, 22 Apr 2026 18:14:42 -0400 Subject: [PATCH 06/14] renaming css chunk --- customize-style.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customize-style.qmd b/customize-style.qmd index 1a61b6f..0c423e8 100644 --- a/customize-style.qmd +++ b/customize-style.qmd @@ -94,7 +94,7 @@ Color theming is controlled through CSS variables. Default values live in `asset For example, within your `assets/style_config_custom.css` file, you would add: -```{css} +``` /* 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 From d1d7318031086609d83c38edab7c3fa0c420dfb3 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 10:25:54 -0400 Subject: [PATCH 07/14] adjusting iframe height --- getting_started.qmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting_started.qmd b/getting_started.qmd index eb020bf..8ce44e3 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -38,7 +38,7 @@ If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.git @@ -135,7 +135,7 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto @@ -262,7 +262,7 @@ _If you have any questions about these updates or files, please tag `@kweav` or @@ -356,7 +356,7 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto From 5697e7157257f6ced90d3128fc6661b510d71f4f Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 10:26:10 -0400 Subject: [PATCH 08/14] switching GA format to cheatsheet --- more_features_ganalytic.qmd | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) 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" --- +
+ + + + +
+ +
+ + + 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 | - +
--- From 9c16370a494c20bc5d03de047ec39db750c455ec Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 10:42:41 -0400 Subject: [PATCH 09/14] sync to cheatsheet --- enroll_sync.qmd | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) 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 --- + +
+ + + + +
+ +
+ + + 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)**→** From fdb94959d191aaa8ab3443174a3f64926fced0e0 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 10:42:53 -0400 Subject: [PATCH 10/14] PR cheatsheet --- writing_content_courses.qmd | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) 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. + +
+ + + + +
+ +
+ + + 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 From ae6c9c74bbcd2d0d62c63ddfc19b0074d6496379 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 11:21:20 -0400 Subject: [PATCH 11/14] create hidden pages --- getting_started.qmd | 325 +------------------------------------------- quarto-course.qmd | 69 ++++++++++ quarto-website.qmd | 71 ++++++++++ rmd-course.qmd | 97 +++++++++++++ rmd-website.qmd | 81 +++++++++++ 5 files changed, 322 insertions(+), 321 deletions(-) create mode 100644 quarto-course.qmd create mode 100644 quarto-website.qmd create mode 100644 rmd-course.qmd create mode 100644 rmd-website.qmd diff --git a/getting_started.qmd b/getting_started.qmd index 8ce44e3..85c9cab 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -49,81 +49,10 @@ If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.git
-
- - - Full setup guide with screenshots - - - -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). - -
+[Full setup guide with screenshots](quarto-course.qmd) [Next Steps](next_steps.qmd) → - ### R Markdown Courses @@ -146,104 +75,7 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto
-
- - - Full setup guide with screenshots - - -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`._ -

- -
+[Full setup guide with screenshots](rmd-course.qmd) --- @@ -273,76 +105,7 @@ _If you have any questions about these updates or files, please tag `@kweav` or
-
- - - Full setup guide with screenshots - - -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). - -
+[Full setup guide with screenshots](quarto-website.qmd) --- @@ -367,87 +130,7 @@ Content is written in `.qmd` files using standard [Quarto syntax](https://quarto
-
- - - Full setup guide with screenshots - - -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`._ -

- -
+[Full setup guide with screenshots](rmd-website.qmd) --- 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/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) → From c849ced40d9511df1a736c8798a64b9c2b84e42d Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Thu, 30 Apr 2026 19:35:24 -0400 Subject: [PATCH 12/14] playing around with the layout --- _quarto.yml | 1 + getting_started.qmd | 201 ++++++++++++++++++------------- styles.css | 281 +++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 396 insertions(+), 87 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index bae00da..6f47b5b 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -70,3 +70,4 @@ format: css: styles.css toc: true include-after-body: resources/footer.html + page-layout: article diff --git a/getting_started.qmd b/getting_started.qmd index 85c9cab..a2a4f52 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -1,191 +1,224 @@ --- title: "Getting Started" toc-depth: 4 +page-layout: full +toc-location: left --- -## Prerequisites for using OTTR +:::: {.intro-grid} -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. +::: {.intro-prereqs} -Please check out these resources if you are not familiar with R Markdown/Quarto. Note that OTTR is also compatible with regular Markdown websites. +## Prerequisites for using OTTR -- 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. +You do not need to be an expert to get started. A few basics will help: -If you are not familiar with **Git and GitHub**, we recommend going through these chapters from our Reproducibility 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. -- [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) +::: -We offer two suggested approaches based on your comfort with Git and GitHub: +::: {.template-chooser} -- **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. +## Choose what you want to build -If you choose OTTR Advanced, we recommend installing [GitKraken](https://www.gitkraken.com/) as a Git client to facilitate branch management. +```{=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, package stats, and other project signals. + +
+``` + +::: + +:::: ## Courses - -### Quarto Courses +::: {.path-header} +**Use this path when:** you are building chaptered learning materials, modules, or a course website. +::: - +### Quarto Courses {.toc-anchor-heading} + +
+ + Quarto Courses + Best for new course builds + **Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -
+
- +::: {.template-actions} [Full setup guide with screenshots](quarto-course.qmd) [Next Steps](next_steps.qmd) → +::: -### R Markdown Courses +
- +### R Markdown Courses {.toc-anchor-heading} -**Template repository:** [ottrproject/OTTR_Template](https://github.com/ottrproject/OTTR_Template) +
+ + R Markdown Courses + Best for `.Rmd` or Bookdown courses + +**Template repository:** [ottrproject/OTTR_Template](https://github.com/ottrproject/OTTR_Template) -
+
- +::: {.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} -**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) +
+ + Quarto Websites + Best for new websites + +**Template repository:** [ottrproject/OTTR_Quarto](https://github.com/ottrproject/OTTR_Quarto) -
+
- +::: {.template-actions} [Full setup guide with screenshots](quarto-website.qmd) ---- - [Next Steps](next_steps.qmd) → +::: + +
-### R Markdown Websites +### R Markdown Websites {.toc-anchor-heading} + +
+ + R Markdown Websites + Best for existing `.Rmd` sites + **Template repository:** [ottrproject/OTTR_Template_Website](https://github.com/ottrproject/OTTR_Template_Website) -
+
- +::: {.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) +::: + +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. -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 +
+ + 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, go to **Settings** > **Actions** > **General**. Make sure you have: -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** +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 @@ -197,10 +230,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/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; + } +} From d3a6c70f91db4da365bbd0e409201b4edf017262 Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan Date: Fri, 1 May 2026 09:46:44 -0400 Subject: [PATCH 13/14] moving toc to the left --- _quarto.yml | 3 +++ getting_started.qmd | 5 ++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/_quarto.yml b/_quarto.yml index 6f47b5b..0b243bb 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -69,5 +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/getting_started.qmd b/getting_started.qmd index a2a4f52..a6d7bb3 100644 --- a/getting_started.qmd +++ b/getting_started.qmd @@ -2,8 +2,7 @@ title: "Getting Started" toc-depth: 4 page-layout: full -toc-location: left ---- +--- :::: {.intro-grid} @@ -35,7 +34,7 @@ You do not need to be an expert to get started. A few basics will help: Dashboards - Metric dashboards for GitHub, analytics, forms, package stats, and other project signals. + Metric dashboards for GitHub, analytics, forms, and package stats. ``` From c6673810a42e4dbdbeb235fadc3416ab03b038aa Mon Sep 17 00:00:00 2001 From: Padmashri Saravanan <65482193+padmashris@users.noreply.github.com> Date: Mon, 4 May 2026 11:59:11 -0400 Subject: [PATCH 14/14] Update customize-style.qmd Co-authored-by: Carrie Wright <23014755+carriewright11@users.noreply.github.com> --- customize-style.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/customize-style.qmd b/customize-style.qmd index 0c423e8..1a8e846 100644 --- a/customize-style.qmd +++ b/customize-style.qmd @@ -92,7 +92,7 @@ Thus as example the reference page looks like this: 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`. -For example, within your `assets/style_config_custom.css` file, you would add: +For example, within your `assets/style_config_custom.css` file, you would add: ``` /*