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](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](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):

Decontamination tools (WF9):

Text processing tools (shared across workflows):

Parameter Icons

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

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     |

Slides, Data Library, and Best Practices

Slides Format

Slides use slides.html with Remark.js:

---
layout: tutorial_slides
logo: "GTN"
title: "Slide Deck Title"
questions:
  - "Question?"
objectives:
  - "Learning objective"
key_points:
  - "Key point"
contributions:
  authorship:
    - username
---

# First Slide Title

Content for first slide

---

# Second Slide Title

.pull-left[
Left column content
]

.pull-right[
Right column content
]

???

Presenter notes go here (after ???)

Key rules:

• --- separates slides
• .pull-left[] / .pull-right[] for two-column layout
• ??? starts presenter notes
• Keep text minimal, use images
• Standard markdown formatting within slides

Data Library Configuration

data-library.yaml defines datasets importable into Galaxy:

---
destination:
  type: library
  name: GTN - Material
  description: Galaxy Training Network Material
  synopsis: Galaxy Training Network Material. See https://training.galaxyproject.org
items:
- name: "Topic Title"
  items:
  - name: "Tutorial Title"
    items:
    - name: 'DOI: 10.5281/zenodo.XXXXXXX'
      description: 'latest'
      items:
      - info: https://doi.org/10.5281/zenodo.XXXXXXX
        url: https://zenodo.org/records/XXXXXXX/files/file1.fasta
        ext: fasta
        src: url
      - url: https://zenodo.org/records/XXXXXXX/files/file2.fastqsanger.gz
        ext: fastqsanger.gz
        src: url

Best Practices

Content Structure

1. Introduction — Brief context, biological motivation, what the tutorial covers 2. Agenda box — Auto-generated TOC 3. Sections with hands-on steps — Alternate theory and practice 4. Questions after hands-on boxes — Self-assessment for learners 5. Conclusion — Summary, link to key points

Writing Style

• Use imperative sentences in hands-on steps ("Click", "Select", "Run")
• Keep tool parameter lists complete — include ALL parameters the user needs to change from defaults
• Use snippets for common Galaxy operations (data import, rename, etc.)
• Include screenshots for complex Galaxy UI interactions
• Explain the "why" alongside the "how"

Learning Design

• Define clear questions and objectives in front matter (use Bloom's taxonomy verbs)
• key_points should directly answer the questions
• Place question boxes after major steps for formative assessment
• Use details boxes for optional deep-dive content
• Use tip boxes for shortcuts and alternative approaches
• Use comment boxes for important context
• Use warning boxes sparingly for critical pitfalls

Data and Workflows

• Keep toy datasets small (tool runs under 10-15 minutes)
• Upload datasets to Zenodo with a DOI
• Include Galaxy workflow (.ga) files in workflows/ directory
• Add workflow tests (-tests.yml) when possible
• Use data-library.yaml for easy data import

Common Pitfalls

• Missing `>` prefix — Every line inside a box must start with >
• Wrong class name — Note: {: .hands_on} uses underscore, not hyphen
• Broken nesting — Solutions need double > > prefix inside questions
• Old `contributors:` field — Use contributions: with sub-fields instead
• Forgetting blank lines — Blank > lines needed between elements inside boxes
• Relative image paths — Always use ../../images/ from tutorial.md

Updating Tutorials for New Tool Versions

When tools are updated in a tutorial's workflow, the tutorial.md must also be updated:

1. Tool version references: Grep for old version strings and update:

   # Find all tool references with old version
   grep -n 'toolshed.*tool_name.*old_version' tutorial.md

   # Update to new version
   # Old: {% tool [MitoHiFi](toolshed.g2.bx.psu.edu/repos/bgruening/mitohifi/mitohifi/3+galaxy0) %}
   # New: {% tool [MitoHiFi](toolshed.g2.bx.psu.edu/repos/bgruening/mitohifi/mitohifi/3.2.3+galaxy0) %}

2. Parameter names in hands-on boxes: If a tool parameter was renamed (e.g., "Assembler" → "Assembler type"), update the *"Parameter Name"* text in hands-on steps.

3. Expected outputs: If tool outputs changed (e.g., NanoPlot 1.46 removed standalone PNG histogram outputs), update references to those outputs in the tutorial text and any screenshot descriptions.

4. Screenshots: Flag for updating when the tool UI changed. Common triggers:

• Flat dropdown → conditional selector
• New required parameters added
• Output datasets changed names or types

Common Tool Replacements in VGP Tutorials

Some tool updates are full replacements (different tool, not just a version bump). These require updating surrounding text, image captions, question blocks, and abbreviations — not just the tool tag.

BUSCO → Compleasm (as of IWC WF4 v0.5, WF8 v3.3):

• Tool: {% tool [Compleasm](...compleasm/0.2.6+galaxy3) %}
• Compleasm has simpler parameters: just genome input + lineage (no Mode, Augustus/Metaeuk, output selection)
• Update: intro text, hands-on params, image captions, question blocks, abbreviations YAML
• Citation: {% cite Huang2023 %}

Monolithic Meryl → Split Meryl tools (as of IWC WF1 v0.6):

• meryl/1.3+galaxy6 → meryl_count_kmers, meryl_groups_kmers, meryl_histogram_kmers (all 1.4.1+galaxy0)
• No more "Operation type selector" dropdown — each tool does one thing
• Parameter names change accordingly

Bellerophon → samtools merge (as of IWC WF8 v3.3):

• Chimeric Hi-C read filtering removed from pipeline
• Replace {% tool [Filter and merge](...bellerophon...) %} with {% tool [Merge BAM Files](...samtools_merge...) %}

Bionano scaffolding removed (no longer in VGP standard pipeline):

• Remove entire Bionano sections, update scaffolding inputs to point directly to contigs
• Remove bionano.cmap from data-library.yaml

Tutorial-Workflow Verification

When updating a tutorial to match a new workflow, verify consistency with these checks:

Cross-check tool versions between tutorial and workflow

import json, re

with open('workflows/main_workflow.ga') as f:
    wf = json.load(f)

# Collect all tool_ids (including subworkflows)
wf_tools = set()
for step in wf['steps'].values():
    if step.get('content_id'):
        wf_tools.add(step['content_id'])
    if step.get('type') == 'subworkflow' and step.get('subworkflow'):
        for substep in step['subworkflow']['steps'].values():
            if substep.get('content_id'):
                wf_tools.add(substep['content_id'])

with open('tutorial.md') as f:
    tutorial = f.read()

tutorial_tools = set(re.findall(r'\{% tool \[.*?\]\((.*?)\) %\}', tutorial))

# Tutorial tools not in workflow = potential version mismatches
mismatches = {t for t in tutorial_tools - wf_tools if 'toolshed' in t}

# Workflow tools not in tutorial = expected for utility/subworkflow tools
# (e.g., compose_text_param, pick_value, map_param_value, param_value_from_file)

Additional checks after a tutorial rewrite

1. Validate workflow JSON: python3 -c "import json; json.load(open('main_workflow.ga'))" 2. Grep for old tool references: search for old tool names (e.g., Kraken2) and old versions (e.g., 2.14.1) 3. Workflow-only tools are OK: utility tools inside subworkflows (e.g., pick_value, map_param_value, compose_text_param) don't need {% tool %} references in the tutorial

Updating tutorials that use external IWC workflows

Some tutorials (e.g., vgp_workflow_training) don't bundle .ga files — they instruct users to import from Dockstore. Update process:

1. Check latest IWC versions via Dockstore API or IWC GitHub releases 2. Fetch the .ga file from GitHub (raw.githubusercontent.com/iwc-workflows/...) to inspect inputs 3. Update `workflows_run_ds.md` snippet version parameter 4. Update input lists: check for new required inputs, changed input types (e.g., separate files → collections), renamed parameters 5. Update tool references: check if QC tools changed (e.g., BUSCO → Compleasm) 6. Mark outdated screenshots with <!-- TODO --> comments rather than leaving incorrect images 7. Grep for old references: search for old tool names and version strings to catch stragglers

GTA track update process

For systematic multi-tutorial updates (e.g., GTA yearly refresh), use the reusable prompt template GTA-track-update-prompt.md which guides 4 iterations:

1. Tutorial inventory — audit staleness, identify candidates 2. Tool version audit — compare tutorial vs Galaxy server versions using MCP 3. Workflow updates — update .ga files and tutorial text 4. Fix known issues — address blockers, compile final action plan

State is tracked in track-content.md (detailed audit) and MANIFEST.md (status overview). Work can be paused and resumed between iterations.

Key tip: The prompt supports a "Target workflows" field where users specify IWC workflows with versions. This enables a top-down update approach (match tutorial to target workflow) rather than bottom-up (discover changes tool by tool).

Galaxy MCP IWC function failures

The MCP functions get_iwc_workflow_details() and search_iwc_workflows() can fail with 'function' object has no attribute 'fn' errors. Always use these fallbacks:

• Version list: https://dockstore.org/api/ga4gh/trs/v2/tools/%23workflow%2Fgithub.com%2Fiwc-workflows%2F{REPO}%2Fmain/versions
• Workflow .ga file: https://raw.githubusercontent.com/iwc-workflows/{REPO}/main/{WORKFLOW_NAME}.ga
• Input inspection: Fetch the .ga file and examine input steps (step 0, 1, 2...) for labels, types, defaults, and optional flags

Always verify actual inputs from the .ga file rather than relying on documentation — upstream changes are frequent and plans may reference outdated versions.

Adapting IWC test files for tutorials

When copying an IWC workflow to a tutorial, adapt the test file:

• Change input data URLs to the tutorial's Zenodo dataset
• Update parameter values (e.g., taxonomic IDs for the tutorial species)
• Keep output assertions minimal but meaningful (check key scaffolds are present/absent)
• The test file name must be main_workflow-tests.yml (matching main_workflow.ga)