Skip to main content

Finalizing and Publishing Your Tutorial

Final steps for cleaning up, submitting for review, and publishing your tutorial via the OSC GitHub Org

Overview

Once you have created your tutorial content (using the tutorial-template as described in the previous chapter) and are ready to publish, there are a few important steps to take to ensure your tutorial is polished, properly licensed, and ready for public consumption. This chapter covers everything you need to do to go from a draft tutorial to a live, citable publication on the OSC website. It includes:

  • A review process overview for getting feedback on your content
  • A pre-publication checklist of tasks to complete before publishing
  • Instructions for making your tutorial live on the website
  • Guidance on setting up a DOI via Zenodo and GitHub releases

This chapter is intended primarily for OSC staff who are responsible for creating and maintaining tutorials, though much of the information will also be relevant to external contributors.

Pre-Publication Checklist

Before your tutorial goes live, work through the following tasks. Some are required in all cases; others are only necessary if your tutorial uses R code. Checking off these items will help ensure a smooth publication process.

0. Verify your content

Before diving into the technical checklist, do a final review of your tutorial content itself:

  • Read through the entire tutorial as if you were a learner. Are there any gaps, unclear instructions, or broken flow?
  • Check all links — internal links (to other pages within your tutorial) and external links (to websites, documentation, etc.). Broken links frustrate readers and undermine credibility. The Link Checker workflow will also catch these on the published site.
  • Verify images and figures — do all images load correctly? Are the file paths correct? (Remember: use absolute paths from the project root, e.g., /assets/images/my-figure.png.)
  • Test code chunks — if your tutorial includes code, run all code chunks fresh (clear your environment and re-execute) to confirm they produce the expected output without errors.
  • Check spelling and grammar — consider using a spell-checker or reading your text aloud to catch awkward phrasing.
Tip

Quarto’s built-in preview is your friend here. Run quarto preview in your project directory and navigate through the rendered site as a visitor would. This catches many issues that are invisible when looking at the raw .qmd files.

1. Confirm the template setup was completed

Before anything else, make sure you finished the setup steps from the Tutorial Template Walkthrough:

  • The placeholder files have been renamed: CITATION-template.cff → CITATION.cff and README-template.md → README.md.
  • _quarto.yml declares project: type: tutorial-template and points repo-url: (and the navbar GitHub links) at your repository, not the template’s.
  • The page-footer copyright line names your authors.
  • The example topic-one/ / topic-two/ folders have been renamed or removed, and the sidebar: matches your actual structure.
  • The template’s demonstration page (renamed to match your project directory, e.g. my-tutorial.qmd) has been deleted or is intentionally kept.

2. Update the CITATION.cff file

The CITATION.cff file contains machine-readable citation metadata for your tutorial. It allows others to cite your work correctly and can be automatically imported into reference managers like Zotero or EndNote. The Check CITATION.cff is Valid workflow validates it on every push once it exists.

Edit this file to include:

  • Author names — list all contributors who should be credited, in the order you want them to appear in the citation
  • ORCID iDs — unique researcher identifiers (see orcid.org). If an author does not have an ORCID, you can leave this field out or note “none”
  • Affiliations — institutional affiliations for each author (e.g., “Open Science Center, LMU Munich”)
  • Version number — should match the version tag you will use for your GitHub release (see Zenodo Integration below)
  • Title — make sure the title matches your tutorial’s title as shown on the website
  • License — the template defaults to CC-BY-SA-4.0 for content and CC0-1.0 for code; only change these if you have a specific reason

If you are unsure about the format, refer to the official CITATION.cff documentation for guidance and examples. You can also spot-check the file in R with cffr::cff_validate().

3. Check your Quarto project (useful if using code chunks)

If your tutorial includes R code chunks, there are two additional steps to ensure your code will build correctly in the deployment pipeline.

a) Run quarto check

This command validates your Quarto project and checks that all code chunks are properly formatted. It helps catch errors early, before they cause build failures during deployment.

quarto check

b) Set up renv for reproducible R environments

The deployment pipeline relies on renv to restore the exact R package versions used in your tutorial. This ensures your code remains reproducible even as packages are updated over time.

Open an R session in your project directory and run:

renv::init()
renv::snapshot()

This will create a lockfile (renv.lock) that captures the precise versions of all R packages your tutorial depends on. Commit this file to your repository.

If your tutorial does not contain any R code chunks, you can skip this step entirely. The Render Quarto Site workflow installs the latest R and infers dependencies from your files when no renv.lock is present, so Python- or Markdown-only tutorials build fine without one.

4. Activate GitHub Pages (one-time setup)

The OSC website is built and deployed using GitHub Pages via the Render Quarto Site workflow mentioned above. Before the automated deployment can work, you need to activate GitHub Pages for your repository by running a one-time command.

From your local project folder, run:

quarto publish gh-pages

This command does three things:

  1. Renders the entire site locally using Quarto
  2. Creates a gh-pages branch in your repository (this branch contains the static HTML files that GitHub Pages serves)
  3. Pushes that branch to GitHub

Once the gh-pages branch exists on GitHub, the Render Quarto Site workflow (included in the template) will automatically deploy your tutorial whenever changes are merged into the main branch.

Warning

If you are unsure about this step or run into errors, reach out to an OSC staff member for assistance. Also note that GitHub Pages cannot be activated for private repositories — your repository must be public.

Live Tutorial Sites

Once you have completed the checklist above and your tutorial has been approved through the review process and you have run quarto publish gh-pages, your tutorial will be live on the OSC website. The URL will follow the pattern: https://lmu-osc.github.io/<tutorial-name>/.

However, you should still run some additional checks to ensure everything is working as expected before beginning to advertise your tutorial to the public. See the next section for a final checklist of items to verify before merging your tutorial into the main tutorials repository.

Final Checks Before Advertising

Zenodo Integration and DOIs

We strongly recommend generating a DOI (Digital Object Identifier) for your tutorial. DOIs make your tutorial easier to cite and allow you to track its impact through citation metrics. We use Zenodo for this purpose.

What is Zenodo?

Zenodo is a free, open-access repository for research outputs — including datasets, software, and publications — developed and maintained by CERN. It provides a simple way to share and preserve research outputs and generates DOIs for every deposit.

What is a GitHub release?

A GitHub release is a way to package and distribute a specific version of your code or content. When you create a release, you can:

  • Include release notes describing what changed
  • Attach binary files (if needed)
  • Generate a tag that points to a specific commit in your repository

When a GitHub repository is connected to Zenodo, creating a new release automatically sends the repository contents to Zenodo, which then generates a DOI for that release.

Versioning with semantic versioning

We use semantic versioning (SemVer) for all tutorial releases. Semantic versioning uses a three-part label in the format MAJOR.MINOR.PATCH — for example, v0.3.0. Here is what each number means:

  • MAJOR — incremented when you make incompatible or breaking changes (e.g., restructuring the entire tutorial)
  • MINOR — incremented when you add functionality or content in a backwards-compatible manner (e.g., adding a new section)
  • PATCH — incremented when you make backwards-compatible bug fixes or minor corrections (e.g., fixing a typo or a broken link)

When creating a new release on GitHub, use a tag like v0.3.0 (with the v prefix followed by the three-part version number). Start with v0.1.0 for the first release and increment from there. This consistent labeling helps users and citation tools understand the significance of each release at a glance. When you are ready to publish the final version of your tutorial, you can use a tag like v1.0.0 to indicate that it is the first major release.

Setting up the connection

To connect your GitHub repository to Zenodo, an OSC staff member with ownership rights over the OSC Zenodo organization needs to:

  1. Log in to Zenodo
  2. Go to the GitHub section in their account settings
  3. Link the OSC GitHub organization to the OSC Zenodo account
Important

This step requires admin-level access to the OSC Zenodo organization. If you need this set up, notify a member of OSC staff who can coordinate it.

Once the connection is active, follow these steps to generate a DOI:

  1. Update CITATION.cff — make sure the version number in CITATION.cff matches the release tag you plan to use
  2. Create a new release on GitHub — go to your repository’s Releases page, click “Draft a new release”, set a version tag (e.g., v0.1.0), add release notes, and publish
  3. Wait for Zenodo — within a few minutes, Zenodo will automatically create a new record and assign a DOI
  4. Add the DOI back into your project — once generated, add it to CITATION.cff and to the citation: block in about.qmd so it appears on the site
Note

While we recommend keeping the CITATION.cff version number and the release tag in sync, this is not strictly required for the DOI to be generated. Zenodo will create a DOI regardless, but matching the numbers avoids confusion for anyone citing your work.

Getting help

If you get stuck at any point, do not hesitate to:

  • Ask a colleague — other OSC staff have been through this process before
  • Open an issue in your tutorial repository and tag someone for help
  • Refer to the Tutorial Template Walkthrough for detailed explanations of the template structure and workflows
  • Check the workflow logs in the Actions tab of your repository on GitHub — error messages often point directly to the problem

Remember: the goal of this process is not just to publish a tutorial, but to ensure it is maintainable, citable, and useful to the community. Taking the time to do it carefully benefits both you and your readers.

Back to top