OTTR-fy an existing repository

Warning

The ottrpal::ottrfy() function is still under development. You may feel free to try it, but please file an issue with OTTR if it does not appear to be working as intended (or if you have other suggestions).

The ottrpal package includes an ottrfy() function that can help add the OTTR files you need to an existing repository. This is especially useful if you already have Quarto (.qmd) files, R Markdown (.Rmd) files, Markdown files, or a Bookdown set of files that you would like to convert into an OTTR course or website.

The current function also includes options for Quarto courses and Quarto websites, but this workflow is newer and still being tested. This method is a bit trickier and riskier than creating a repository from scratch, so we recommend generally avoiding this strategy unless it is unavoidable.

This set of steps also assumes you are more familiar with GitHub.

Warning

You cannot OTTR-fy a repository that was created as a fork, even if you detach the fork. The OTTR GitHub Actions workflows are set up to work from a regular repository, so start from a new repository instead of a fork.

Requirements for OTTR-fying a repository:

Need to have either Quarto, Markdown, or R Markdown documents in the top of your repository that you are seeking to publish.
Needs to be a public GitHub repository.
Need to have the ottrpal R package installed.

install.packages("ottrpal")

If your installed version of ottrpal does not recognize the type options below, install the development version from GitHub:

if (!("remotes" %in% installed.packages())) {
  install.packages("remotes")
}
remotes::install_github("ottrproject/ottrpal")

Step 1: Choose your OTTR flavor

The ottrfy() function needs to know what kind of OTTR site you want to make. Choose the type that matches your existing files and your final goal:

`type`	Use this when…	Files added from…
`"quarto"`	You are making a Quarto course website. This is a good match for existing `.qmd` course chapters.	`OTTR_Quarto`
`"rmd"`	You are making an R Markdown / Bookdown course website. This is the best match for existing `.Rmd` course chapters.	`OTTR_Template`
`"quarto_web"`	You are making a Quarto website that is not organized like a course/book.	`OTTR_Quarto_Website`
`"rmd_web"`	You are making an R Markdown website that is not organized like a course/book.	`OTTR_Template_Website`

Not sure which OTTR template is right for you? Answer two quick questions and we’ll point you to the right setup guide.

Step 2: Set up your repository settings

Before you run ottrfy(), set up the repository permissions and GH_PAT secret that the OTTR GitHub Actions workflows will need. This is important because ottrfy() adds the workflow files and then you will open a pull request that should trigger those workflows.

Go to Settings > Actions > General. Make sure you have:

Given Read and write permissions.
Checked Allow GitHub Actions to create and approve pull requests.

Then click Save.

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 with repo and workflow scopes checked.

Step 3: Add OTTR files to your current repository

Navigate to the top of your repository and run ottrpal::ottrfy() with the type you chose above.

For a Quarto course:

ottrpal::ottrfy(type = "quarto")

For an R Markdown / Bookdown course:

ottrpal::ottrfy(type = "rmd")

For a Quarto website:

ottrpal::ottrfy(type = "quarto_web")

For an R Markdown website:

ottrpal::ottrfy(type = "rmd_web")

By default, existing files will not be overwritten. If you have reviewed the files and intentionally want to replace existing OTTR setup files, use overwrite = TRUE.

ottrpal::ottrfy(type = "quarto_web", overwrite = TRUE)

Note

Before using overwrite = TRUE, review these filenames carefully so that you do not accidentally replace any files you meant to keep.

You can also use path if you are running the function from somewhere other than the repository you want to OTTR-fy.

ottrpal::ottrfy(path = "path/to/my/repository", type = "quarto")

OTTR-fying files

The function downloads the necessary files to run OTTR in your repository. Every flavor gets the shared automation and checking files below, then ottrfy() adds the template-specific files for the type you choose.

Note

Before using overwrite = TRUE, review these filenames carefully so that you do not accidentally replace any files you meant to keep.

Shared files

.github/workflows/check-url.yml
.github/workflows/pull_request.yml
.github/workflows/delete-preview.yml
config_automation.yml
resources/dictionary.txt
resources/ignore-urls.txt
resources/exclude_files.txt

Flavor-specific files

index.qmd
_quarto.yml
references.bib
img/favicon.ico
img/logo.png
.github/workflows/render-all.yml
resources/images/figure/

index.Rmd
_bookdown.yml
_output.yml
assets/big-image.html
assets/footer.html
assets/open-new-tab.html
book.bib
.github/workflows/render-all.yml

_quarto.yml
styles.css
.github/workflows/render-site.yml

_site.yml
styles.css
resources/header.html
.github/workflows/render-site.yml

Step 4: Review and commit the added files

After running ottrfy(), check your files and make sure nothing unexpected has happened to your original files. Then create a branch, commit the added files, push the branch to GitHub, and open a pull request.

The OTTR automation checks should happen on this pull request automatically. Render preview check will almost certainly fail until you complete the next step.

If they do not automatically start running, you may also want to check in your Settings > Actions that Allow all actions and reusable workflows is chosen.

Step 5: Add your content files to the site configuration

You will almost certainly find that the Render preview check will fail (and possibly the spelling and URL checks).

One reason that this will fail is that you will need to edit your site configuration file to list your content files in the order they should appear.

For type = "rmd", edit _bookdown.yml.
For type = "quarto" or type = "quarto_web", edit _quarto.yml.
For type = "rmd_web", edit _site.yml.

See this section for more information about these checks and what they are.

Note

For Quarto repositories, make sure _quarto.yml includes output-dir: docs. The OTTR workflows expect the rendered site to be written to the docs directory, so this setting is required for the workflow to run correctly.

For example:

project:
  type: website # or the project type already used by your site
  output-dir: docs

Note

For Quarto preview rendering, use only HTML format while you are getting the OTTR workflow running. Some preview-rendering workflows can fail when _quarto.yml includes more than one output format, such as both html and pdf.

Note

Don’t merge this pull request until the preview, spelling, and URL checks pass or you have reviewed and accepted the remaining failures.

← Getting Started Next Steps →