| name | galaxy-training-material |
| description | Expert in Galaxy Training Network (GTN) tutorial development. GTN markdown syntax, special boxes, tool references, snippets, YAML front matter, and best practices for writing and updating training materials in the galaxyproject/training-material repository. |
| version | 1.0.0 |
| allowed-tools | Read, Grep, Glob, Bash |
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"
topic_type: technology
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
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
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 URLdatasets_import_from_data_library.md — Import from data libraryhistories_create_new.md — Create new historydatasets_rename.md — Rename datasetdatasets_change_datatype.md — Change datatype (pass datatype="...")collections_build_list.md — Build dataset listcollections_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" textn: 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
- 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 |
