Guidelines for contributing, including adding new content or editing existing materials.
We highly recommend reading Ten simple rules for making training materials FAIR before creating a new training material and following the FAIR (Findable, Accessible, Interoperable, Reusable) principles for training materials.
There are two options to run the website locally and preview your training materials before pushing them.
Option 1: Using Ruby and Bundler
You need Ruby and Bundler installed. Then run:
# Install required gems
bundle install
# Start the Jekyll server
bundle exec jekyll serve --trace --livereload --port 4000
Open http://127.0.0.1:4000/training/ (Server address) in your browser to view the website.
Option 2: Using Docker
Build and run the containerized version:
# Build the Docker image
docker build . -t dekcd
# Run the container
docker run -it -p 4000:4000 dekcd
Then open http://127.0.0.1:4000/training/ in your browser.
This section describes the required structure, conventions, and submission workflow for contributing a new tutorial. Please follow these guidelines to ensure consistency, reusability, and maintainability across the repository.
All tutorials must be stored in the _tutorials directory. Each tutorial must have its own subdirectory, organized by tutorial name and version:
_tutorials/<tutorial-name>/<tutorial-version>
For example:
_tutorials/nanopore/main
The tutorial version is typically named main, but you can use an event- or release-specific name, such as summer-school-2026.
Inside the version directory, choose one of the following structures:
tutorial.md by default.part1.md and part2.md). Link these files from the final tutorial.md.Recommended approach: use a modular structure
The modular structure is recommended because it:
Important: The version directory must always contain a tutorial.md as the main file. This is the file that will be rendered as the tutorial.
All tutorials must define their metadata at the very top of the main file tutorial.md using YAML front matter. Do not place metadata in auxiliary Markdown files (e.g., part1.md, part2.md).
Example metadata header:
---
layout: tutorial_hands_on
title: Introduction to basic Unix commands
description: "This is the introduction to the basic shell commands."
time_estimation: 2H30M
level: beginner
keywords: ["shell"]
questions:
- Which questions are addressed by the tutorial?
objectives:
- The learning objectives of the tutorial
key_points:
- The take-home messages
- They will appear at the end of the tutorial
version: main
life_cycle: active
contributions:
authorship:
- Max Mustermann
editing:
- Erika Mustermann
funding:
- de.KCD
---
Short description that summarizes the tutorial.
## Section title
Enter your tutorial content here.
The following fields are mandatory unless stated otherwise:
layout: use tutorial_hands_on as the default layout.title: tutorial title as displayed on the tutorial collection page.description: a concise summary of the tutorial content.time_estimation: estimated duration of the tutorial. This must conform to the following pattern:
/^(?:([0-9]+)[Hh])?(?:([0-9]+)[Mm])?(?:([0-9.]+)[Ss])?$/level: the learners level of ability in the topic being taught according to the BioSchema TrainingMaterial Profile 1.0-RELEASE. Examples of skill levels include beginner, intermediate or advanced.keywords: keywords or tags used to describe the content. Multiple entries in a keywords list are delimited by commas.
Example:
keywords: ["bioinformatics", "python"]questions: a list of key questions addressed by the tutorial.objectives: a list of learning objectives.key_points: summary points presented at the end of the tutorial.version: specifies the tutorial version (main by default).life_cycle: indicates the development status of a training material according to the BioSchema TrainingMaterial Profile 1.0-RELEASE. Options are active, under development, and archived.
Example:
life_cycle: under development
Development status of tutorials
- under development: early-stage development. Content may be incomplete, untested, and subject to significant changes. This status typically applies until a complete first draft is available.
- active: complete, reliable, and well-maintained tutorial. Only minor updates are expected.
- archived: the tutorial is no longer maintained and may be removed in the future.
contributions: categorized list of contributors. Examples include authorship, editing, funding, testing, infrastructure, and translation. In the funding section, list the name of the organization that supported the training material. Ensure that the organization’s name matches an entry in _data/contributions.yml. If your organization is not listed, please add its name to _data/contributions.yml and place the organization’s logo in /assets/img/ folder.The following fields are optional but recommended where applicable:
zenodo_link: link to the input data for the tutorial on Zenodo.follow_up_training: a list of resources that the reader of the material could follow at the end of the tutorial.For extended metadata options and advanced patterns, please refer to the Galaxy Training Network tutorial guidelines.
Add a concise summary of your tutorial Please provide a brief abstract after the metadata section. The abstract should summarize the main topic, purpose, and scope of the tutorial in 2–3 concise sentences.
Do not add a heading or title for the abstract. This summary provides learners with a quick overview of the tutorial and is also used to populate the
abstractmetadata field in the Bioschemas TrainingMaterial Profile.
If you choose a modular structure, assemble the final tutorial using Jekyll’s include directive:
Your introductory text.
{% include _tutorials/intro-python/main/part1.md %}
Additional content.
This approach allows flexible composition while keeping individual sections reusable.
A typical modular tutorial may look like:
_tutorials/
intro-python/
main/
part1.md
part2.md
tutorial.md
If you have any data or images that you would like to add to the tutorial, please place them in the tutorial folder.
This section outlines the standardized components used to structure tutorial content, including Table of Contents (TOC), instructional boxes and image handling.
To automatically generate a Table of Contents from your section headings, add the following snippet directly below the metadata section in your content:
> <agenda-title>Table of Contents</agenda-title>
> Your text (optional).
> 1. TOC
> {:toc}
>
{: .agenda}
Mathematical expressions should be written in LaTeX. To render an equation, enclose the expression with double $$ on both sides.
Example (inline expression):
$$ a^2 + b^2 = c^2 $$
This will be rendered as:
\[a^2 + b^2 = c^2\]You can also use standard LaTeX math environments (such as equation, align, eqnarray, etc.) inside the $$ ... $$ delimiters to create more complex formulas and multi-line equations.
Example (multi-line equation using eqnarray):
$$\begin{eqnarray}
x' &=& &x \sin\phi &+& z \cos\phi \\
z' &=& - &x \cos\phi &+& z \sin\phi \\
\end{eqnarray}$$
This will be rendered as:
\[\begin{eqnarray} x' &=& &x \sin\phi &+& z \cos\phi \\ z' &=& - &x \cos\phi &+& z \sin\phi \\ \end{eqnarray}\]Notes
- Use standard LaTeX syntax for all mathematical expressions.
- Equations are rendered by enclosing them in double dollar signs
$$ ... $$, which can be used for both inline and display-style formulas.- If an inline equation does not render correctly with
$$ ... $$, use LaTeX inline math delimiters instead:\( a^2 + b^2 = c^2 \)This will be rendered as: \( a^2 + b^2 = c^2\)- LaTeX math environments (such as
equation,align,aligned,cases, andeqnarray) should be enclosed within$$ ... $$to ensure proper rendering.- Complex expressions, multi-line equations, and aligned formulas can be created using these environments.
To enhance the learning experience, tutorials use a set of predefined “boxes” implemented via styled blockquotes. These visually distinguish different types of content such as tasks, explanations, tips, and assessments.
Example: Question and Solution Box
> <question-title>Questions</question-title>
> 1. Question 1
> 2. Question 2
>
> > <solution-title>Answers</solution-title>
> > 1. Answer 1
> > 2. Answer 2
> >
> {: .solution}
>
{: .question}
This structure creates a nested box where solutions are revealed within the question block:
Questions
- Question 1
- Question 2
Answers
- Answer 1
- Answer 2
Box titles are defined using a custom HTML-like tag structure, such as
The following boxes are available and should be used consistently:
{: .overview} summaries{: .key_points} take-home messages{: .tip} practical advice or shortcuts{: .warning} important cautions{: .comment} explanatory notes{: .hands_on} or {: .hands-on} exercises or tasks{: .question} assessment questions{: .solution} answers to questions{: .details} supplementary information{: .feedback} learner feedback prompts{: .code-in} input code blocks{: .code-out} output or resultsFoldable box types (solution, tip, comment, details) allow you to show or hide the content on the same page. The title line of these boxes is always visible, making it easier to scan long explanatory boxes and reducing visual overload in tutorials.
Tasks
- Create each box and see how it looks.
- Create one with a nested box.
Usage examples:
Tasks
- List of tasks
- …
Details Here put some text…
Tip Here put some useful information…
Comment Here put some comments…
Code In ls -lhimport pandas as pd
Code Out # code output
Questions
- Question 1
- Question 2
Answers
- Answer 1
- Answer 2
Images must be referenced using the relative_url filter:
{: .responsive-img }
![figure-title]() this is standard Markdown image syntax. The text inside the brackets (figure-title) becomes the alt text, which improves accessibility and is displayed if the image fails to load./training/path/to/image the relative_url ensures that the correct baseurl defined in _config.yml is automatically prepended. This prevents broken links when the site is hosted in a subdirectory.{: .responsive-img } CSS class ensures that images do not exceed content width and scale proportionally on smaller screens.Additional resources If you need an additional material to learn how to format the tutorial content, i.e. to wrap parts of the text in the special block quotes, please refer to the Software Carpenters’ Formatting episode.
Please also refer to the Markdown Cheatsheet to learn more how to use Markdown.
If your tutorial exists in multiple versions (e.g., adapted for different audiences or events), organize them using version-specific subdirectories:
_tutorials/<tutorial-name>/
main/
tutorial.md
summer-school-2026/
tutorial.md
Each version should be self-contained or consistently structured using include.
Tutorials are categorized into thematic groups (e.g., Unix, Metagenomics) for navigation and discoverability.
To register your tutorial:
nanopore) to the _data/tutorial_groups.yml fileIf no suitable group exists:
For example, if your tutorial is stored in a folder named nanopore, add it to the relevant group (or incubator for review) as follows:
- title: Incubator
description: Tutorials in this group are under review.
tutorials:
- nanopore
You can add your name, ORCID, and/or GitHub profile to the _data/contributors.yml file. Your ORCID will be used to identify and attribute your contribution when your tutorial is registered in TeSS.
For example:
- name: Max Mustermann
ORCID: https://orcid.org/xxxx-xxxx-xxxx-xxxx
Github: https://github.com/max-mustermann
Once your tutorial is ready to publish, create a new branch, commit your changes, submit a pull request for review. You may optionally open an issue to describe your contribution before or alongside your pull request.
If all the required metadata fields are completed correctly, tutorials can be registered in TeSS with minimal additional effort. Using the Bioschemas TrainingMaterial Profile ensures the metadata is machine-readable and interoperable, enabling automated harvesting, improving discoverability, and supporting seamless integration into the ELIXIR training ecosystem without manual curation.
This guide explains how to create presentation slides with Quarto and make them available on the training materials platform.
Presentations in this repository are written in Quarto and rendered as RevealJS slides. The generated slides are HTML files that can be viewed in a browser or exported to PDF for distribution.
The typical workflow is:
slides.qmd file.Important: Name the Quarto slides slides.qmd. This file is rendered and linked from training materials platform.
What is Quarto? Quarto is an open-source publishing system for scientific and technical content. It can generate many different output formats, including:
- Articles and reports
- Websites and books
- Dashboards and interactive documents
- Presentations
In this guide, we focus exclusively on creating presentations using the revealjs format.
Create a file named slides.qmd in your tutorial directory: _tutorials/<TUTORIAL-NAME>/<TUTORIAL-VERSION>/slides.qmd
A minimal presentation looks like this:
---
title: "Your Presentation Title"
subtitle: "Your Subtitle"
author: "Your Name"
date: "2026-06-26"
format: revealjs
---
## Slide 1
Your content here
## Slide 2
More content here
Shared presentation information—such as title, author, and output settings—is placed at the root level of your YAML block. For RevealJS format-specific metadata, please refer to this documentation.
If you already have presentation slides in PowerPoint .pptx format, you can convert them to a Quarto Markdown .qmd file using pandoc:
pandoc --from=pptx --to=markdown --output=slides.qmd --extract-media=images slides.pptx
Here, --extract-media extracts images and other media from the input file and saves them in the specified folder.
After running the command, you should have a slides.qmd file and images folder containing all extracted images.
Pandoc does not automatically create all the Quarto metadata required for your slides. Add the following YAML header to the top of slides.qmd:
---
title: "Your Presentation Title"
subtitle: "Your Subtitle"
author: "Your Name"
date: "2026-06-26"
format: revealjs
---
Important Always review the generated
slides.qmdbefore publishing it.Pandoc can preserve much of the content and structure of the original presentation, but the conversion is not always perfect. You may need to manually adjust lists and formatting.
After making any necessary changes, render the slides.qmd with Quarto to check that the final presentation looks as expected.
Slides are created using Markdown headings level 1 (#) or level 2 (##). You can also separate slides with a horizontal rule (---):
- Item 1
- Item 2
---
- Item 1
- Item 2
Note: The best way to get a sense for the capabilities of RevealJS is this demo presentation. Check out the source code for the demo to see how the slides were created.
RevealJS provides many features, including incremental content, speaker notes, interactive elements, code highlightning, custom themes, and export to PDF. The following resources are usefule when building presentations:
Resources
While creating your slides, it is recommended to use Quarto’s live preview mode:
quarto preview slides.qmd
This command automatically renders the presentation, starts a local web server, and opens the slides in your browser. Any changes you make to slides.qmd are automatically re-rendered and refreshed in the browser, making it easier to develop and test your presentation.
Once your presentation is ready, generate the final HTML version by running:
quarto render slides.qmd --to revealjs
This command creates the final presentation file in the same directory, named slides.html.
After verifying that the presentation renders correctly:
slides.qmd and any associated assets (images, logos, etc.).After a few minutes, your presentation will appear on the platform. Open the Collection of Tutorials page and look for for tutorial in the Slides column to access the published presentation.
Alternatively, you can upload your slides as a PDF file named slides.pdf. The PDF will then be available on the Collection of Tutorials page in the Slides column. It will appear as <tutorial_version> (PDF). You can click the file to open it and view the slides in presentation mode directly in your web browser.
Note: PDF slides are more difficult to maintain and update than Quarto markdown. However, they can be a quick solution if you need to make the slides available without further editing.
Learning pathwayss organize multiple tutorials into coherent, structured curricula. Each pathway defines a sequence of modules, where each module groups related tutorials under a shared theme.
To define a new pathway create a markdown file named <pathway_title>.md and place it in the _pathways directory.
Each pathway file must include YAML front matter describing its structure, modules, and associated tutorials.
Template:
---
layout: pathway
title: Title of the Learning Pathway
description: A concise summary of the pathway’s scope and objectives.
tags: [a list of keywords]
pathway:
- section: "Module 1: The module title"
description: A short explanation of the module’s focus
tutorials:
- name: tutorial name
version: main
- section: "Module 2: The module title"
description: A short explanation of the module’s focus
tutorials:
- name: another tutorial
version: main
editorial_board:
- name: contributor Name
orcid: contributor ORCID
---
The layout field must be set to pathway to ensure correct rendering of the pathway page. Each tutorial entry must include name (which must exactly match the corresponding tutorial folder name) and version (selected from the available versions of that tutorial).
After defining the pathway, create a new branch, commit the pathway file, and submit a pull request for review.
If you would like to contribute your training materials to the Galaxy Training Network (GTN), please follow the official guidelines for creating a new tutorial and formatting content.
This platform is fully compatible with GTN in terms of metadata structure and formatting conventions. This compatibility enables seamless transfer of materials between GTN and this platform. In practice, this means:
To incorporate specific GTN tutorials into this platform, you can use git sparse-checkout to efficiently retrieve only the required content:
git clone --depth 1 --filter=blob:none --sparse https://github.com/galaxyproject/training-material.git temp-training
cd temp-training
git sparse-checkout set topics/statistics/tutorials/classification_machinelearning
_tutorials/ directory:
cp -r topics/statistics/tutorials/classification_machinelearning ../_tutorials/<tutorial_name>
cd ..
rm -rf temp-training