Next Steps

Now that you’ve set up a shell for your OTTR repository, there are some next steps that you need to take, and some steps that we highly recommend. Additionally, there are further customizations you may want to consider.

✓

Necessary

Required before publishing

Further customization

Necessary Next Steps

Changing the title

The title is specified on the index.qmd/index.Rmd page in the yml header. Modify the yaml header to change the title for your course.

---
title: "Title of Course"
---

Note that if one of the chapter .qmd or .Rmd files has a title in the yml that comes first alphabetically, it will be shown as the title of the course. Hence, avoid having yml header titles for the chapter files.

Customizing branding and style

Once your repository is set up, it’s worth updating the visual identity of your course or website to reflect your project. For full instructions, see the Customizing Style page.

Key things to update:

Colors — color theming is controlled through CSS variables. Default values live in assets/style_config_default.css, and course-specific overrides should go in assets/style_config_custom.css. To customize branding, update variables such as --link-color, --accent-color, and --highlight-color. You generally should not edit color hex codes directly in assets/style.css.
Favicon — convert your logo to .ico format using favicon.io, save it in assets/, and reference it in the YAML header.
Logo — logos in the table of contents sidebar are configured via _output.yml. Update the image URL and the link to your GitHub repo.
Style set — the template defaults to the JHU Data Science Lab style. If you are building an ITN or DataTrail course, copy the relevant files from the style-sets/ folder to switch styles.

Give credits to contributors

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

Key things to update:

About.qmd/About.Rmd — already included in the template. Fill in author names for each role, remove inapplicable rows, and make sure role names grammatically match (singular vs. plural).
Required rows — all courses should include rows for Template Publishing Engineers, Publishing Maintenance Engineer, Technical Publishing Stylists, and Package Developers. See the full credits table reference.
Coursera — add the credits table URL as an ungraded plugin at the start of your course, right after the introduction.
Leanpub — ensure About.md is listed in Book.txt and it will be included automatically.

Highly Recommended Next Steps

Click any card to expand full instructions.

Enroll for sync updates

Stay up to date with template updates

Full instructions

Add jhudsl-robot as a Collaborator.
Add your repository name to the .github/sync.yml file of the OTTR template you created your repository from.
Submit your repo name via a Google Form, an Issue, or a PR

For more details about enrolling for sync updates, click here.

Clean out template placeholder files

Remove example content that comes with the template and replace it with your own.

Full instructions

Safe to delete:

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

Do NOT delete:

index.qmd or index.Rmd
Anything inside .github/workflows/ — these run all the automated checks and rendering
resources/ — contains the spell-check dictionary and screenshot helpers
Configuration files: _bookdown.yml, _output.yml, book.bib, _quarto.yml

Update the README

Replace template placeholder text with a description of your course, its audience, and how to contribute.

Full instructions

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

At minimum, update:

The title and description
Any links that point to the template repository (replace with your own repo URL)
Author and contact information

Add a license

Clarify how others can use and share your content by adding a license file to your repository.

Full instructions

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

To add a license on GitHub:

Go to your repository’s main page.
Click Add file > Create new file and name it LICENSE.
GitHub will offer a license picker — select your preferred license and commit.

Add your repository link to the sidebar

Link your GitHub repository from the course sidebar so readers can find the source, suggest edits, or file issues.

Full instructions

For R Markdown courses, update _output.yml:

bookdown::gitbook:
  config:
    edit:
      link: https://github.com/YOUR-ORG/YOUR-REPO/
      text: "GitHub Repository"
    download: no
    sharing: no

For Quarto, update _quarto.yml:

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

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

Set up a feedback channel

Make it easy for learners to report problems or leave feedback to improve your course over time.

Full instructions

Two good approaches:

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

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

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

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

Cite your sources

Manage references with a BibTeX file and cite sources inline throughout your course.

Full instructions

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

Add references to book.bib in alphabetical order. For articles with a DOI, use doi2bib.org or ZoteroBib to generate a BibTeX entry to copy in.
Cite in text using @key (inline) or [@key] (parenthetical). Separate multiple citations with semicolons: [@key-1; @key-2].
References list — for Bookdown, keep References.Rmd as the last file in _bookdown.yml. For Quarto books, keep references.qmd as the last chapter in _quarto.yml.
Suppress per-chapter references in Bookdown by adding split_bib: false to _output.yml. Quarto books should use the #refs div in references.qmd for the end-of-book bibliography.

Set up Google Analytics

Track how people are finding and using your content with Google Analytics.

Full instructions

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

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

Additional Customizations to Consider

See the customization menu below for options including Docker configuration, borrowing chapters, Google Docs compatibility, and more.

Customize Style

Customize Robots

Customize Docker

← Getting Started Start writing! Enroll for Sync Updates →