// Create a new numbered lesson page within an existing training module. Use when adding a new topic like '05_error_handling.md' to an existing course.
| name | new-lesson |
| description | Create a new numbered lesson page within an existing training module. Use when adding a new topic like '05_error_handling.md' to an existing course. |
Create a new lesson page within an existing training module.
See ../shared/repo-conventions.md for directory structure and file conventions.
Note: A "module" is a complete training course (like "Hello Nextflow" or "Side Quests"), while a "lesson" is a single numbered page within that module (like "01_hello_world.md").
Follow these steps:
Ask the user:
Create the markdown file following the naming convention: [number]_[title_with_underscores].md
03_hello_workflow.mdUse this lesson template structure:
# Part [N]: [Title]
[Introduction paragraph explaining what this lesson covers]
---
## 1. [First Major Section]
[Content explaining the concept]
### 1.1. [Subsection]
[Detailed explanation with examples]
```bash
command example
```
expected output
[Summary of what was learned in this section]
[Preview of next section]
[Continue pattern...]
[Content with code examples]
#!/usr/bin/env nextflow
process EXAMPLE {
// highlighted lines
}
[Summary]
[Next steps or move to next lesson]
4. Include appropriate elements:
- Code blocks with proper formatting (linenums, titles, highlighting)
- **For `hl_lines`**: Before writing this attribute, identify which lines you want highlighted, then count their position from line 1 of the snippet. Blank lines count. The `hl_lines` values are completely independent of `linenums`.
- Before/After comparisons using tabbed blocks where relevant:
```markdown
=== "After"
```groovy title="example.nf" hl_lines="5" linenums="1"
// corrected code
```
=== "Before"
```groovy title="example.nf" hl_lines="5" linenums="1"
// broken code
```
```
- Admonitions: `!!! note`, `!!! tip`, `!!! warning`, `??? exercise`
- Console output examples
- Clear explanations for beginners
5. Remind the user to:
- Add the lesson to `docs/en/mkdocs.yml` nav section in the correct module
- Create corresponding Nextflow example scripts if needed
- Add solution files for any exercises in `[module]/solutions/`
- Test any Nextflow examples before committing
- Run heading validation: `uv run .github/check_headings.py --fix docs/**/*.md`
- Preview locally with `mkdocs serve` or Docker to verify formatting
- Translations are handled automatically - when merged to master, the translation workflow will create PRs for each language
Run comprehensive validation and review checks including heading numbering, TODO/FIXME comments, Nextflow script conventions, orphaned files, admonition syntax, lesson structure, formatting, content accuracy, and teaching effectiveness. Use when validating, reviewing, or checking training materials quality, lesson quality, or before committing changes.
Walk through a training tutorial as a user would, progressively building examples exactly as instructed, running all commands, and verifying results against solutions. Use when testing tutorials end-to-end or validating that instructions are correct and complete.
Add an interactive exercise with solution to an existing lesson. Creates properly formatted exercise and solution admonition blocks. Use when a lesson needs hands-on practice.
Verify that hl_lines attributes in markdown code blocks correctly highlight the intended lines. Use when reviewing documentation with code examples, especially Before/After comparisons, or when highlights seem incorrect.
Review inline code in markdown files for proper formatting and syntax highlighting. Check for missing backticks on CLI flags, filenames, and code elements. Verify that inline syntax highlighting (#!groovy) is used appropriately. Use when reviewing documentation or quiz questions.
Set up a Docker container for running Nextflow training examples. Handles basic setup, Docker-outside-of-Docker (DooD) for containerized processes, ARM Mac platform emulation, and troubleshooting. Use when you need to run Nextflow examples in a consistent environment.