Including a new topic

Author(s) orcid logoAvatarBérénice Batut
Editor(s) orcid logoAvatarHelena Rasche
  • How to include a new topic?

  • What kinds of Topics are possible?

  • Create a new topic

  • Set up the metadata for a topic

Time estimation: 30 minutes
Supporting Materials:
Last modification: Jan 23, 2023
License: Tutorial Content is licensed under Creative Commons Attribution 4.0 International License The GTN Framework is licensed under MIT


Each training material is related to a topic. All training materials (slides, tutorials, …) related to a topic are found in a dedicated directory (e.g. transcriptomics directory contains the material related to exome sequencing analysis).

Directory structure

Each topic has the following structure:

├── metadata.yaml
├── images
├── docker
│   ├── Dockerfile
├── slides
│   ├── index.html
├── tutorials
│   ├── tutorial1
│   │   ├──
│   │   ├── slides.html
│   │   ├── data-library.yaml
│   │   ├── workflows
│   │   │   ├──
│   │   │   ├──
│   │   ├── tours
│   │   │   ├── tour.yaml

images directory

The images directory collects all images/pictures needed for the training materials related to the topic, i.e pictures for the slides or the tutorials.

Images shared between several topics are in the shared/images directory at the root.

All images for the slides must be in images directory. The images must be in good quality. The sources (svg or other) of the images must also be added to the images directory. We encourage you to use yEd to easily generate diagrams and Inkscape for any other images.

tutorials directory

This directory collects the materials related to the topic, one material per subdirectory, though it may consist of slides, tutorials, or both.

The tutorials are hands-on built for workshop and self-training, with description of the whole infrastructure needed to run the tutorial on any Galaxy instance (tools, data library, etc).

The templates for the tutorials are different from the other pages to help users to focus on the content of the tutorial. To improve the output of the tutorial, several metadata are mandatory for every tutorials, such as the requirements or the objectives of the tutorials. Boxes are also used to highlight some key points as the hands-on or the tips.

The content of each tutorial is generated with Jekyll from a Markdown file and some metadata (e.g. the requirements, the Zenodo link, the questions) defined inside the metadata of the related topic.

Comment: Contributing

Want to contribute to a tutorial? Check out our training materials about that.

Sometimes, an hands-on tutorial is not the most appropriate format for a tutorial and slides are better.

docker directory

For each topic, a flavored Docker image must integrate the tools needed for the tutorials. The corresponding image must be based on official Galaxy Docker images.

The docker image will also integrate the Galaxy tours available for each topics and the workflows.


In this tutorial, we will deal with:

  1. Introduction
    1. Directory structure
  2. Creating a new topic with it’s own materials
    1. Defining the topic
    2. Creating the skeleton for the topic
    3. Adapt the metadata for your topic
  3. Creating a tag based topic
    1. Defining the topic
  4. Conclusion

There are two kinds of topics we will cover: topics with their own materials, and synthetic topics that are based solely on a tag. For large collections of materials around a single central theme a topic with materials is a good choice. However, sometimes you will want to highlight materials spread across numerous or disparate topics like e.g. Cancer or SARS-CoV-2 tutorials where you might have individual tutorials on assembly or transcriptomics, but you’d like a single page listing all of them.

Creating a new topic with it’s own materials

Defining the topic

When we structured the repository, we decided to use as topics the categories that are used in the ToolShed. The ToolShed assigns a category to each tool. Therefore, to decide where to put your tutorial, have a look at which ToolShed’s category the main tools in your tutorial belong. For example, this tutorial will rely on the NCBI Blast+ tool.

Hands-on: Defining the topic for the tutorial
  1. Search for NCBI Blast+ on the ToolShed
  2. Check in which category it has been placed


    In which topic will you put the new tutorial?

    If we search for NCBI Blast+ in the ToolShed, it is placed in 2 categories (bottom): “Next Gen Mappers”, and “Sequence Analysis”. We decided to put it in “Sequence analysis” because this is the most general one for this tutorial.

In this tutorial, we want to add a new topic called about “my-favorite-topic”.

Creating the skeleton for the topic

Once the topic name has been chosen, we can create it.

Hands-on: Create all the required files and folders structures automatically
  1. Open a terminal
  2. Run (by adapting the information between the quotes)

    $ planemo training_init \
             --topic_name "my-favorite-topic" \
             --topic_title "Test" \
             --topic_target "use" \
             --topic_summary "Summary of the topic"
  3. Check that a new directory has been generated in topics
  4. Check that a YAML file with your topic name has been generated in metadata folder
  5. Make sure that Jekyll is running

    Comment: Jekyll

    Want to learn how to start Jekyll? Check out our tutorial to serve the website locally

  6. Check if the topic has been correctly added at http://localhost:4000/training-material/

Adapt the metadata for your topic

Several metadata are defined in metadata.yaml file in your topic folder to :

A dictionary/map

Free Text

The internal identifier for a topic, it should be the same as the folder name.


name: epigenetics
name: sequence-analysis
name: admin

Required Pattern: Must match the following regular expression


Free Text

The type of topic, some have subtly different behaviours.

should be used for admin and developer topics that are not scientifically focused.
Only used for galaxy-interface type topics
Topics which are not necessarily Galaxy focused but expand into broader communities
These topics use galaxy for some analysis
Specific to topics related to instruction of Galaxy

Possible Values:

  • admin-dev
  • basics
  • data-science
  • use
  • instructors


type: "admin-dev"
type: "basics"
type: "data-science"
type: "use"
type: "instructors"

Free Text

Title of the topic, this is displayed for users to see.


title: Proteomics
title: Variant Analysis

Free Text

A longer description of the contents of this topic


summary: Statistical Analyses for omics data and machine learning using Galaxy tools

List of Items

Free Text

Any custom CSS you might want to apply to a specific topic. This could be overriding e.g. the masthead colour (beware, will potentially conflict with themes.)

This is generally not a recommended property to set on topics, and something that is only used as part of outreach efforts to import content into the GTN.


custom_css: - :root { --brand-color: red; }

Free Text

The image ID for an image which contains all of the tools and data for this topic.




true to hide your tutorial from the topic page (optional). This is useful if you need a tutorial for a workshop, but have not finished making it up to GTN standards.

Free Text

An edam ontology id that describes the topic.


edam_ontology: topic_3173

Required Pattern: Must match the following regular expression


Free Text

Link to a gitter channel that is more relevant for this topic than the default. E.g. a single cell topic, you could use Galaxy-Training-Network/galaxy-single-cell to link to their specific chat room in all of the child tutorials by default.


gitter: Galaxy-Training-Network/galaxy-single-cell
gitter: galaxy-genome-annotation/Lobby

Free Text

A logo identifier (e.g. GTN) should be used by default, but may be swapped out for special logos from the assets folder.

Free Text

The alt text for the logo (MANDATORY).

Free Text

A custom image to show on the link preview in external applications (e.g. when the URL is pasted into Twitter)


og_image: /assets/images/gat.png

Required Pattern: Must match the following regular expression


List of Items


- - |
    authors: "Vaudel M, et al."
    title: "Shedding light on black boxes in protein identification."
    link: ""
    summary: "An extensive tutorial for peptide and protein identification, available at The material is completely based on freely available and open-source tools."

Sequence Value (List of items)
A dictionary/map

Free Text

Free Text

Free Text

Free Text

List of Items

List of resources that the reader of the material should be familiar with before starting this training. The structure is identical to follow_up_training.


- type: internal
  topic_name: statistics
      - age-prediction-with-ml

Sequence Value (List of items)
A dictionary/map

Free Text

the type of link

Possible Values:

  • internal


type: "internal"

Free Text

The name of the topic

List of Items

List of required tutorials inside that topic

List of Items

For large topics, we can define subtopics and create multiple tutorial lists, which separates the tutorials to help users find content that interests them more quickly.

A dictionary/map

Free Text

Subtopic ID, this should match what is used in tutorials.


id: single-cell

Required Pattern: Must match the following regular expression


Free Text

Subtopic title, which is displayed for users to see.


title: Maintaining a Production Galaxy
title: Single-cell RNA-seq

Free Text

A human readable textual description of a subtopic.


description: - "Start here if you are new to RNA-Seq analysis in Galaxy"
- "These tutorials take you from raw sequencing reads to pathway analysis"
- "Tutorials about analysis of single-cell RNA-seq data"
- "Tutorials using a single published single-cell RNA-seq dataset for a variety of analyses"


false to hide your topic from the production GTN. This is useful if you need a topic for a workshop, but have not finished making it up to GTN standards.


If this is a synthetic tag based topic (no tutorials of it’s own) then you must set this flag to indicate it as such, otherwise you will find yourself with an empty topic page.

Hands-on: Update the new topic to the website
  1. Open the metadata.yaml file in your topic folder
  2. Fill the correct metadata of the topic
  3. Make sure that Jekyll is running

    Comment: Jekyll

    Want to learn how to start Jekyll? Check out our tutorial to serve the website locally

  4. Check how it changes the local website


For large topics, we can define subtopics and create multiple tutorial lists, within a topic’s metadata.yaml

name: transcriptomics
type: use
title: Transcriptomics
summary: Training material for all kinds of transcriptomics analysis.
docker_image: ""


- id: introduction
  title: "Introduction"
  description: "Start here if you are new to RNA-Seq analysis in Galaxy"
- id: end-to-end
  title: "End-to-End Analysis"
  description: "These tutorials take you from raw sequencing reads to pathway analysis"
- id: visualisation
  title: "Visualisation"
  description: "Tutorials covering data visualisation"

Each subtopic has:

  • an ID, used as a reference in the tutorial
  • a short descriptive title
  • a longer description discussion what is contained in that subtopic

Tutorials can be assigned to subtopics by adding e.g. subtopic: singlecell to the tutorial metadata. An example of this subtopic division can be found in the admin section

Creating a tag based topic

For tag based topics, first ensure that all of the relevant tutorials share a single tag, across all materials that should be included in this view.

Defining the topic

Compare with other topic level metadata files in the metadata/ directory of the training material. Then create a file of your own naming the topic and providing maintainers and so on. We will use the Covid-19 synthetic topic as an example:

name: "covid19"
type: "use"
title: "SARS-CoV-2"
summary: "Tutorials covering analysis of SARS-CoV-2 (COVID 19)"
tag_based: true

  - wm75

gitter: galaxyproject/sars-cov-2

As you can see it is very short, and there are only a handful of important points:

  • tag_based must be set to true
  • name must be equal to the tag name, that’s being used across tutorials.
  • subtopics must not be set.

With this done, all materials tagged covid19 will be aggregated and available under this synthetic topic. They are organised by the “parent” topic, so e.g. assembly tutorials are collected together and transcriptomics tutorials are also in a section together, similar to how other tutorials define subtopics.


We just created a new topic. We can now fill it by creating new tutorials

Key points
  • A new topic can be easily added for new tutorials

Frequently Asked Questions

Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Contributing to the Galaxy Training Material topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum


Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Click here to load Google feedback frame

Citing this Tutorial

  1. Bérénice Batut, Including a new topic (Galaxy Training Materials). Online; accessed TODAY
  2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

author = "Bérénice Batut",
title = "Including a new topic (Galaxy Training Materials)",
year = "",
month = "",
day = ""
url = "\url{}",
note = "[Online; accessed TODAY]"
	doi = {10.1371/journal.pcbi.1010752},
	url = {},
	year = 2023,
	month = {jan},
	publisher = {Public Library of Science ({PLoS})},
	volume = {19},
	number = {1},
	pages = {e1010752},
	author = {Saskia Hiltemann and Helena Rasche and Simon Gladman and Hans-Rudolf Hotz and Delphine Larivi{\`{e}}re and Daniel Blankenberg and Pratik D. Jagtap and Thomas Wollmann and Anthony Bretaudeau and Nadia Gou{\'{e}} and Timothy J. Griffin and Coline Royaux and Yvan Le Bras and Subina Mehta and Anna Syme and Frederik Coppens and Bert Droesbeke and Nicola Soranzo and Wendi Bacon and Fotis Psomopoulos and Crist{\'{o}}bal Gallardo-Alba and John Davis and Melanie Christine Föll and Matthias Fahrner and Maria A. Doyle and Beatriz Serrano-Solano and Anne Claire Fouilloux and Peter van Heusden and Wolfgang Maier and Dave Clements and Florian Heyl and Björn Grüning and B{\'{e}}r{\'{e}}nice Batut and},
	editor = {Francis Ouellette},
	title = {Galaxy Training: A powerful framework for teaching!},
	journal = {PLoS Comput Biol} Computational Biology}


Congratulations on successfully completing this tutorial!
Developing GTN training material
This tutorial is part of a series to develop GTN training material, feel free to also look at:
  1. Creating a new tutorial
  2. Contributing with GitHub via command-line
  3. Creating Slides
  4. Overview of the Galaxy Training Material
  5. Tools, Data, and Workflows for tutorials
  6. Running the GTN website online using GitPod
  7. GTN Metadata
  8. Generating PDF artefacts of the website
  9. Updating diffs in admin training
  10. Principles of learning and how they apply to training and teaching
  11. Running the GTN website locally
  12. Design and plan session, course, materials
  13. Teaching Python
  14. Contributing with GitHub via its interface
  15. Adding auto-generated video to your slides
  16. Including a new topic
  17. Creating content in Markdown
  18. Adding Quizzes to your Tutorial
  19. Creating Interactive Galaxy Tours