galaxy-training-material

What this skill does

# 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

```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:

```yaml
---
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:

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

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

#### Agenda (Table of Contents)

```markdown
> <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)

```markdown
> <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

```markdown
> <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

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

#### Tip

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

#### Warning

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

#### Details (Collapsible)

```markdown
> <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

```markdown
> <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:
```markdown
> > <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

```markdown
{% 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