galaxy-training-material

Galaxy Training Material Expert

Expert knowledge for writing and updating tutorials in the Galaxy Training Network (GTN) repository (github.com/galaxyproject/training-material). Covers the custom markdown syntax, file structure, and pedagogical conventions.

When to Use This Skill

• Writing or editing GTN tutorial content (tutorial.md files)
• Creating new tutorials or topics
• Understanding GTN-specific markdown syntax (boxes, tool refs, snippets, icons)
• Reviewing or fixing tutorial formatting issues
• Adding slides, workflows, or data libraries to tutorials
• Updating YAML front matter metadata

Supporting Files

For additional details, see the following files in this directory:

• WORKFLOW-VERIFICATION.md — Cross-checking tool versions between tutorials and workflows, updating IWC-based tutorials, GTA track update process, MCP fallbacks, adapting test files.
• BEST-PRACTICES.md — Slides format, data library configuration, content structure and writing style best practices, learning design, common pitfalls, updating tutorials for new tool versions.

Repository Structure

Topic Layout

topics/{topic_name}/
├── metadata.yaml           # Topic config (name, type, editorial_board, subtopics)
├── images/                 # Shared images for all tutorials in this topic
├── faqs/                   # Topic-level FAQs
└── tutorials/
    └── {tutorial_name}/
        ├── tutorial.md         # Main tutorial content (required)
        ├── tutorial.bib        # BibTeX citations (optional)
        ├── slides.html         # Presentation slides (optional)
        ├── data-library.yaml   # Zenodo dataset definitions
        ├── workflows/
        │   ├── index.md        # layout: workflow-list
        │   ├── *.ga            # Galaxy workflow files (JSON)
        │   └── *-tests.yml     # Workflow test definitions
        └── faqs/               # Tutorial-specific FAQs
            └── index.md

Topic metadata.yaml

---
name: "assembly"
type: "use"                    # "use" or "admin"
topic_type: technology         # technology, science, instructors, basics
title: "Assembly"
summary: "Description of the topic"
docker_image: "quay.io/galaxy/assembly-training"
edam_ontology: ["topic_0196"]
requirements:
  - type: "internal"
    topic_name: introduction
  - type: "internal"
    topic_name: sequence-analysis
    tutorials:
      - quality-control
editorial_board:
  - github-username
subtopics:
  - id: subtopic_id
    title: "Subtopic Title"
    description: "Description"

Tutorial YAML Front Matter

Every tutorial.md starts with YAML front matter between --- delimiters:

---
layout: tutorial_hands_on
title: "Tutorial Title"
zenodo_link: "https://zenodo.org/records/XXXXXXX"
questions:
  - "What biological question does this address?"
  - "How do we use tool X for task Y?"
objectives:
  - "Perform task X using Galaxy"
  - "Interpret output of tool Y"
time_estimation: "1H30M"
level: Introductory              # Introductory, Intermediate, Advanced
key_points:
  - "Take-home message 1"
  - "Take-home message 2"
contributions:
  authorship:
    - github-username
  editing:
    - github-username
  funding:
    - organization-id
  testing:
    - github-username
tags:
  - tag1
  - tag2
subtopic: subtopic_id           # Must match a subtopic id in topic metadata.yaml
edam_ontology:
  - topic_XXXX
requirements:
  - type: "internal"
    topic_name: introduction
    tutorials:
      - galaxy-intro-short
recordings:
  - youtube_id: VIDEO_ID
    length: 29M
    galaxy_version: "24.1"
    date: '2024-09-20'
follow_up_training:
  - type: "internal"
    topic_name: assembly
    tutorials:
      - assembly-decontamination
---

Important notes:

• Use contributions: with sub-fields (authorship, editing, funding, testing), NOT the older contributors: field
• time_estimation format: "30M", "1H", "1H30M", "2H"
• All usernames must exist in the root CONTRIBUTORS.yaml
• level determines visual badge (Introductory/Intermediate/Advanced)

Special Markdown Syntax

Box Types

All pedagogical boxes follow this pattern:

> <type-title>Title Text</type-title>
>
> Content here
>
{: .class_name}

Every line inside the box must start with > (blockquote prefix).

Agenda (Table of Contents)

> <agenda-title></agenda-title>
>
> In this tutorial, we will cover:
>
> 1. TOC
> {:toc}
>
{: .agenda}

Always placed after the introduction, before the first section. The 1. TOC / {:toc} generates automatic table of contents from headings.

Hands-on (Step-by-Step Instructions)

> <hands-on-title>Descriptive Step Title</hands-on-title>
>
> 1. {% tool [Tool Display Name](toolshed.g2.bx.psu.edu/repos/owner/repo/tool_id/version) %} with the following parameters:
>    - {% icon param-file %} *"Input file"*: `dataset_name`
>    - {% icon param-select %} *"Parameter name"*: `Option value`
>    - {% icon param-text %} *"Text parameter"*: `some text`
>    - {% icon param-check %} *"Checkbox param"*: `Yes`
>
> 2. Examine the output file by clicking {% icon galaxy-eye %} (eye icon)
>
{: .hands_on}

Formatting rules for hands-on boxes:

• Number each major step
• Tool name links use {% tool [Name](id) %} syntax
• Parameters are bulleted under the tool step, indented by 4 spaces from the >
• Parameter names are in "quotes with italics"
• Parameter values are in `backticks`
• Use the appropriate icon for each parameter type

Question + Solution

> <question-title>Descriptive Question Title</question-title>
>
> 1. What is the N50 of the assembly?
> 2. How many contigs are there?
>
> > <solution-title></solution-title>
> >
> > 1. The N50 is 15 Mb
> > 2. There are 42 contigs
> >
> {: .solution}
>
{: .question}

Solutions are nested inside questions (double > > prefix). Solutions are collapsed by default.

Comment

> <comment-title>Optional Title</comment-title>
>
> Additional context or explanation that's helpful but not critical.
>
{: .comment}

Tip

> <tip-title>Helpful Tip Title</tip-title>
>
> A practical hint to help the learner.
>
{: .tip}

Warning

> <warning-title>Important Warning</warning-title>
>
> Something that could cause problems if ignored.
>
{: .warning}

Details (Collapsible)

> <details-title>Click to Expand</details-title>
>
> Extended information hidden by default. Good for background
> information that not all learners need.
>
{: .details}

Code Input/Output

> <code-in-title>Bash</code-in-title>
> ```bash
> echo "Hello Galaxy"
> ```
{: .code-in}

> <code-out-title>Output</code-out-title>
> ```
> Hello Galaxy
> ```
{: .code-out}

For side-by-side display, wrap both in:

> > <code-in-title>Bash</code-in-title>
> > ```bash
> > command
> > ```
> {: .code-in}
>
> > <code-out-title>Output</code-out-title>
> > ```
> > output
> > ```
> {: .code-out}
{: .code-2col}

Tool References

{% tool [Human-Readable Name](toolshed.g2.bx.psu.edu/repos/owner/repo/tool_id/version) %}
{% tool [Cut](Cut1) %}
{% tool [MultiQC](toolshed.g2.bx.psu.edu/repos/iuc/multiqc/multiqc/1.11+galaxy1) %}

• The text in [] is the display name
• The text in () is the full tool ID (ToolShed URL or short built-in ID)
• Version is included in the tool ID after the last /

Common VGP Assembly Tool IDs (current versions)

Core pipeline tools (WF1–WF8):

Tool	Tool ID	Version
Cutadapt	toolshed.g2.bx.psu.edu/repos/lparsons/cutadapt/cutadapt/5.2+galaxy1	5.2+galaxy1
Meryl - count kmers	toolshed.g2.bx.psu.edu/repos/iuc/meryl_count_kmers/meryl_count_kmers/1.4.1+galaxy0	1.4.1+galaxy0
Meryl - groups of kmers	toolshed.g2.bx.psu.edu/repos/iuc/meryl_groups_kmers/meryl_groups_kmers/1.4.1+galaxy0	1.4.1+galaxy0
Meryl - histogram	toolshed.g2.bx.psu.edu/repos/iuc/meryl_histogram_kmers/meryl_histogram_kmers/1.4.1+galaxy0	1.4.1+galaxy0
GenomeScope	toolshed.g2.bx.psu.edu/repos/iuc/genomescope/genomescope/2.1.0+galaxy0	2.1.0+galaxy0
Hifiasm	toolshed.g2.bx.psu.edu/repos/bgruening/hifiasm/hifiasm/0.25.0+galaxy3	0.25.0+galaxy3
gfastats	toolshed.g2.bx.psu.edu/repos/bgruening/gfastats/gfastats/1.3.11+galaxy1	1.3.11+galaxy1
Compleasm	toolshed.g2.bx.psu.edu/repos/iuc/compleasm/compleasm/0.2.6+galaxy3	0.2.6+galaxy3
Merqury	toolshed.g2.bx.psu.edu/repos/iuc/merqury/merqury/1.3+galaxy4	1.3+galaxy4
minimap2	toolshed.g2.bx.psu.edu/repos/iuc/minimap2/minimap2/2.28+galaxy2	2.28+galaxy2
purge_dups	toolshed.g2.bx.psu.edu/repos/iuc/purge_dups/purge_dups/1.2.6+galaxy1	1.2.6+galaxy1
BWA-MEM2	toolshed.g2.bx.psu.edu/repos/iuc/bwa_mem2/bwa_mem2/2.3+galaxy0	2.3+galaxy0
PretextMap	toolshed.g2.bx.psu.edu/repos/iuc/pretext_map/pretext_map/0.2.3+galaxy0	0.2.3+galaxy0
Pretext Snapshot	toolshed.g2.bx.psu.edu/repos/iuc/pretext_snapshot/pretext_snapshot/0.0.5+galaxy1	0.0.5+galaxy1
YaHS	toolshed.g2.bx.psu.edu/repos/iuc/yahs/yahs/1.2a.2+galaxy3	1.2a.2+galaxy3

Decontamination tools (WF9):

Tool	Tool ID	Version
FCS Adaptor	toolshed.g2.bx.psu.edu/repos/richard-burhans/ncbi_fcs_adaptor/ncbi_fcs_adaptor/0.5.0+galaxy0	0.5.0+galaxy0
FCS GX	toolshed.g2.bx.psu.edu/repos/iuc/ncbi_fcs_gx/ncbi_fcs_gx/0.5.5+galaxy2	0.5.5+galaxy2
DustMasker	toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_dustmasker_wrapper/2.16.0+galaxy0	2.16.0+galaxy0
blastn	toolshed.g2.bx.psu.edu/repos/devteam/ncbi_blast_plus/ncbi_blastn_wrapper/2.16.0+galaxy0	2.16.0+galaxy0
parse_mito_blast	toolshed.g2.bx.psu.edu/repos/iuc/parse_mito_blast/parse_mito_blast/1.0.2+galaxy0	1.0.2+galaxy0
Filter by length	toolshed.g2.bx.psu.edu/repos/devteam/fasta_filter_by_length/fasta_filter_by_length/1.2	1.2

Text processing tools (shared across workflows):

Tool	Tool ID	Version
sed (Text transformation)	toolshed.g2.bx.psu.edu/repos/bgruening/text_processing/tp_sed_tool/9.5+galaxy2	9.5+galaxy2
Replace Text	toolshed.g2.bx.psu.edu/repos/bgruening/text_processing/tp_replace_in_line/9.5+galaxy2	9.5+galaxy2
Concatenate	toolshed.g2.bx.psu.edu/repos/bgruening/text_processing/tp_cat/9.5+galaxy2	9.5+galaxy2

Parameter Icons

Use these icons before parameter names in hands-on boxes:

Icon	Syntax	Use For
File input	{% icon param-file %}	Single file parameter
Multiple files	{% icon param-files %}	Multi-file input
Collection	{% icon param-collection %}	Dataset collection
Text	{% icon param-text %}	Free text input
Select	{% icon param-select %}	Dropdown selection
Checkbox	{% icon param-check %}	Yes/No checkbox
Toggle	{% icon param-toggle %}	Toggle switch
Repeat	{% icon param-repeat %}	Repeat/add section

Other Useful Icons

{% icon galaxy-eye %}          # View/eye icon (inspect dataset)
{% icon galaxy-pencil %}       # Edit icon (edit attributes)
{% icon galaxy-delete %}       # Delete icon
{% icon galaxy-history %}      # History icon
{% icon tool %}                # Tool icon
{% icon question %}            # Question mark
{% icon congratulations %}     # Celebration

Snippets (Reusable Content)

Include shared FAQ content:

{% snippet faqs/galaxy/datasets_import_via_link.md %}
{% snippet faqs/galaxy/histories_create_new.md %}
{% snippet faqs/galaxy/datasets_rename.md %}
{% snippet faqs/galaxy/datasets_change_datatype.md datatype="fasta" %}
{% snippet faqs/galaxy/collections_build_list_paired.md %}

Snippets accept optional parameters (key="value"). Common snippets:

• datasets_import_via_link.md — Import data from URL
• datasets_import_from_data_library.md — Import from data library
• histories_create_new.md — Create new history
• datasets_rename.md — Rename dataset
• datasets_change_datatype.md — Change datatype (pass datatype="...")
• collections_build_list.md — Build dataset list
• collections_build_list_paired.md — Build paired list

Collection snippets accept customization parameters:

{% snippet faqs/galaxy/collections_build_list_paired.md datasets_description="the two Hi-C datasets (SRR7126301_1 and SRR7126301_2)" n="2" %}

• datasets_description: overrides the default "all datasets" text
• n: sets the number shown in "n of N selected" prompt

You can change the box type of a snippet:

{% snippet faqs/galaxy/histories_create_new.md box_type="hands_on" %}

Workflow Snippets

To let users import a workflow bundled in the tutorial's workflows/ directory:

{% snippet faqs/galaxy/workflows_run_trs.md path="topics/assembly/tutorials/my-tutorial/workflows/main_workflow.ga" title="My Workflow" %}

For tutorials that import workflows from Dockstore (e.g., IWC workflows):

{% snippet faqs/galaxy/workflows_run_ds.md title="Genome profile analysis (WF1)" dockstore_id="github.com/iwc-workflows/kmer-profiling-hifi-VGP1/main" version="v0.6" %}

Use workflows_run_ds.md (Dockstore) when the tutorial references external IWC workflows. Use workflows_run_trs.md (TRS) when the workflow .ga file is bundled in the tutorial's workflows/ directory.

Images

![Alt text for accessibility](../../images/image_name.png "Caption shown below figure")

• Images go in topics/{topic}/images/
• Path from tutorial.md is ../../images/
• Alt text is required for accessibility
• Caption in quotes is optional but recommended

Citations

Define in tutorial.bib (BibTeX format):

@article{key2024,
  title={Article Title},
  author={Last, First and Other, Author},
  journal={Journal Name},
  year={2024},
  doi={10.xxxx/xxxxx}
}

Reference in tutorial:

{% cite key2024 %}

Internal Links

[Link text]({% link topics/topic_name/tutorials/tutorial_name/tutorial.md %})

Math (LaTeX)

Inline: $$ x^2 + y^2 = z^2 $$
Block (on its own line): $$ \sum_{i=1}^{n} x_i $$

Tables

Standard markdown tables:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| data     | data     | data     |