Creating content in Markdown

Overview

Questions:
  • How to write a tutorial with hands-on?

  • What are the different boxes?

  • How can I add a caption to an image?

Objectives:
  • Create hands-on

  • Use the different boxes

Time estimation: 15 minutes
Supporting Materials:
Last modification: May 19, 2022
License: Tutorial Content is licensed under Creative Commons Attribution 4.0 International License The GTN Framework is licensed under MIT

Introduction

Once we have set up the infrastructure, we are ready to write the tutorial.

Agenda

In this tutorial, we will cover:

  1. Metadata
    1. Listing contributors
  2. Content
    1. Adding images with captions
    2. Writing mathematical expressions
    3. Tables and Matrices
  3. Improving the learning experience
    1. Overview box
    2. Agenda box
    3. Hands-on box
    4. Tool Links
    5. Questions and solution boxes
    6. Tips box
    7. Comments boxes
    8. Details box
    9. Key points box
    10. Warning box
    11. Nested boxes
    12. Code box
    13. FAQs (snippets)
    14. Footnotes
    15. Icons
    16. Abbreviations
    17. Choose Your Own Tutorial
  4. Citations
  5. Automatic Jupyter Notebooks & RMarkdown
    1. Currently Supported Languages
    2. Restrictions
    3. Enabling the system
    4. JupyterLite & Pyodide
  6. Spanish Translation Project
    1. Other Languages
    2. Footnotes (Rendered)

The tutorial’s content should be placed in the file tutorial.md. Its syntax and structure are simple, and will have the following structure:

---
layout: tutorial_hands_on

title: Title of the tutorial
zenodo_link: ''
questions:
- Which biological questions are addressed by the tutorial?
- Which bioinformatics techniques are important to know for this type of data?
objectives:
- The learning objectives are the goals of the tutorial
- They will be informed by your audience and will communicate to them and to yourself
  what you should focus on during the course
- They are single sentences describing what a learner should be able to do once they
  have done completed tutorial
- You can use Bloom's Taxonomy to write effective learning objectives
time_estimation: ''
key_points:
- The take-home messages
- They will appear at the end of the tutorial
contributors:
- contributor1
- contributor2
---
# Introduction
{:.no_toc}

blabla

# Section 1

blabla

## Subsection 1

blabla

# Section 2

blabla

## Subsection 2

blabla

# Conclusion
{:.no_toc}

blabla

Metadata

The tutorial.md needs to start with some metadata at the top:

  • layout: tutorial_hands_on: keep the default
  • title: title of the tutorial (it will appear on the tutorial page and the topic page)
  • level: Introductory, Intermediate or Advanced
  • enable: false to hide your tutorial from the topic page (optional)
  • zenodo_link: link on Zenodo to the input data for the tutorial
  • contribuors: eveybody who has contributed to this tutorial (usernames must match those in CONTRIBUTORS.yaml file)

hands_on Hands-on: Fill the basic metadata

  1. Update the tutorial information in the header section of your tutorial:

     title: "Similarity search with BLAST"
    
  2. (Optional) Add the Zenodo link (if created)

This information is used to display the data from the topic and tutorial page. They are also used to check which information is missing for the tutorials.

We also define metadata related to the pedagogical content of the tutorial, which will appear at the top (“Overview” box) and bottom of the online tutorial:

  • requirements: list of resources that the reader of the material should be familiar with before starting this training:
    • type: the type of link (internal or external)

    For internal, i.e. inside the Galaxy Training Material:

    • topic_name: name of the topic
    • tutorials: list of required tutorials inside of the topic

    For external:

    • title: title of the external resource
    • link: URL to the external resource
  • time_estimation: an estimation of the time needed to complete the hands-on
  • questions: list of questions that will be addressed in the tutorial
  • objectives: list of learning objectives for the tutorial

    A learning objective is a single sentence describing what a learner will be able to do once they have done the tutorial

  • key_points: list of take-home messages

    This information will appear at the end of the tutorial

  • follow_up_training: list of resources that the reader of the material could follow at the end of the tutorial

    • type: the type of link (internal or external)

    For internal, i.e. inside the Galaxy Training Material:

    • topic_name: name of the topic
    • tutorials: list of required tutorials inside of the topic

    For external:

    • title: title of the external resource
    • link: URL to the external resource

    They will be displayed at the end of the tutorial.

  • subtopic: if the topic has multiple subtopics defined, you can assign your tutorial to one of those subtopics here. Without this, the tutorial will appear in the “Other tutorials” section on the topic page.

For this category of metadata, we have taken inspiration from what Software Carpentry has done and particularly what they described in their Instructor training.

hands_on Hands-on: Fill out the pedagogical metadata

  1. Define 2 questions that will be addressed during the tutorial and add them to the metadata
  2. Define 2 learning objectives for the tutorial and add them to the metadata

comment When filling the pedagogical metadata

We recommend that you fill out the questions and the learning objectives before starting writing the tutorial content. You can still refine them afterwards, but it will help to guide you in developing your tutorial, and gives you some time to think beforehand on what topics are worth being covered.

For the take-home messages, it is easier to define them once the tutorial is written and you identified the issues.

Listing contributors

All tutorials and slides must give credit to all contributors. This can be any type of contribution, adding them in GitHub, creating images for it, etc.

  1. Make sure all contributors are listed in the CONTRIBUTORS.yaml file. Each contributor is defined in this file like:

    contributor-username:                 # GitHub username (if the contributor has one)
      name: Full Name                     # mandatory
      joined: 2020-06                     # mandatory
      email: saskia.hiltemann@gmail.com   # optional
      twitter: shiltemann                 # optional
      linkedin: shiltemann                # optional
      gitter: shiltemann                  # optional
      orcid: 0000-0003-3803-468X          # optional
      bio: Researcher at EMC              # optional
    
  2. Add all contributors to the metadata of the tutorial or slide deck:

    contributors:
      - contributor-username
      - shiltemann
      - hexylena
    

    Make sure these names match the usernames you used in the CONTRIBUTORS.yaml file.

  3. Optional: Specifying types of contributions. If you want to give more detailed credit for conributions, you can do the following (instead of step 2 above)

    contributions:
      authorship:
        - shiltemann
      editing:
        - bebatut
        - hexylena
      funding:
        - carpentries
      testing:
        - userX
      ux:
        - userY
      infrastructure:
        - userZ
    

    To define a funding body in the CONTRIBUTORS.yaml there are a few extra fields available:

    erasmusplus:
      name: Erasmus+ Programme
      joined: 2020-09
      avatar: "https://www.erasmusplus.nl/assets/images/logo.png"
      github: false
      funder: true
      funding_id: 2020-1-NL01-KA203-064717
      funding_statement: |
         This project ([`2020-1-NL01-KA203-064717`](https://ec.europa.eu/programmes/erasmus-plus/projects/eplus-project-details/#project/2020-1-NL01-KA203-064717)) is funded with the support of the Erasmus+ programme of the European Union. Their funding has supported a large number of tutorials within the GTN across a wide array of topics.
         <img src="https://gallantries.github.io/assets/images/logosbeneficaireserasmusright_en.jpg" alt="eu flag with the text: with the support of the erasmus programme of the european union. "  loading="lazy">
    

    Funding bodies will be credited at the bottom of the tutorial with the appropriate funding statement, and will get a page in the hall of fame listing all tutorials that list them as a funder.

    For an example of how this all looks, see the R basics tutorial (top and bottom of the tutorial).

Content

The tutorial’s content is written directly after the section of metadata. This is written in Markdown, a simple markup language.

comment Markdown

Check this cheatsheet to learn more how to use Markdown.

The Markdown content is then transformed into a user friendly webpage through a templating system. With this approach, there is no need to add the name of every tutorial each time, since they are automatically added based on the tutorial’s metadata.

To help developing the tutorial, we recommend to create a workflow of the different steps of the tutorial inside Galaxy first, and then you can create the structure of the tutorial automatically from that:

hands_on Hands-on: Create the structure of the tutorial from a workflow

  1. Create a small workflow with one or two steps on a running Galaxy instance
  2. Add the topic name as Tag and the tutorial title as Annotation/Notes to the workflow using the workflow editor.
  3. Get the workflow id
    1. Go the “Share” page of the workflow
    2. Copy the information after id= in the URL of the page
  4. Get your API key for this Galaxy instance
    1. Click on User –> Preferences
    2. Click on Manage API key
    3. Click on Create a new key (if none is available)
    4. Copy the API key
  5. Generate the skeleton of the tutorial locally

    $ planemo training_generate_from_wf \
             --topic_name "my-topic" \
             --tutorial_name "my-new-tutorial" \
             --galaxy_url "URL to Galaxy instance in which you created the workflow" \
             --galaxy_api_key "Your API key on the Galaxy instance" \
             --workflow_id "ID of the workflow on the Galaxy instance" \
             --zenodo_link "URL to the Zenodo record (Optional)"
    

    comment Using a local workflow

    It is also possible to download the workflow locally (with the .ga extension), and then run a slightly different command:

    $ planemo training_generate_from_wf \
             --topic_name "my-topic" \
             --tutorial_name "my-new-tutorial" \
             -- workflow PATH/to/the/file.ga \
             --zenodo_link "URL to the Zenodo record (Optional)"
    
  6. Inspect the generated tutorial.md

The generated tutorial is structured with:

  • An introduction, to give an overview of the tutorial with its use cases, data, and methods
  • Multiple sections representing the steps of the analysis, complete with automatically generated hands-on blocks, as practicing is a vital part of the learning process
  • A conclusion to summarize what has been done in the tutorial (with a graphic)

hands_on Hands-on: Filling out the structure of the tutorial

  1. Fill out the “Introduction” with a general introduction of the tutorial and a small description of the dataset (goals)
  2. Rename/restructure the sections with several levels and more explication
  3. Add some theory about the tool used to introduce each section
  4. Add a small conclusion and relate the results to the original question

Adding images with captions

To add an image in Markdown file, we need to use the markdown syntax for this: <img src="../../images/image.png" alt="proper alt text describing the image for visually impaired learners. " loading="lazy">.

We have also added a small plugin to handle captions for each image:

A textual description of the image.
Figure 1: Example of an image with a caption

The prefix “Figure 1.” is automatically added before its caption. This is done with the following Markdown syntax:

<img src="../images/image.png "Example of an image with a caption"" alt="A textual description of the image. "  loading="lazy">

We can also cross-reference images inside our Markdown with an anchor. For example, we can link to the previous figure using [the display text](#figure-nb) (changing nb with the image’s number).

Guidelines on Alt vs Figcaption Text

While both the alt attribute and the figcaption element provide a way to describe images, the way we write for them is different. alt descriptions should be functional; figcaption descriptions should be editorial or illustrative.

via thoughtbot.com

As an example for this image:

alt text.
Figure 2: Example of an image with a caption
<img src="path/to/image.png "Example of an image with a caption"" alt="Alt text (shown when image cannot be displayed). "  loading="lazy">
Field Appropriate Contents
alt text Image of cell membrance with an embedded protein with central pore. DNA is shown splitting and entering the pore, an electrical signal comes out reading A C T or G.
figure caption Using nanopore sequencing, a single molecule of DNA or RNA can be sequenced without the need for PCR amplification or chemical labeling of the sample. (Image from: Nanopore sequencing: The advantages of long reads for genome assembly)

Writing mathematical expressions

Mathematical expressions can be written in LaTeX, and are automatically rendered with MathJax.

Surround your math expression with two $ signs on each side (like in LaTeX math blocks):

  • inline expressions, e.g. $$ 5 + 5 $$ will be rendered as \(5 + 5\)
  • block expressions, e.g. $$ 5 + 5 $$ will be rendered in its own line block as

    \[5 + 5\]

Dollar signs are therefore reserved characters for instructing the templating system to open/close LaTeX math blocks. If you want to use a $ within your expression, you will need to escape it: $$ a + 3\$ = 5\$ $$ will be rendered as: \(a + 3\$ = 5\$\)

LaTeX code that uses the pipe symbol | in inline math statements may lead to a line being recognized as a table line by the templating system. This can be avoided by using the \vert command instead of |

Tables and Matrices

Tables can be generated using markdown by using the | symbol to indicate column dividers, and -- for table headers:

|       | Obs1 | Obs2 | Obs3 |
|------ |--------------------|
| Feat1 | 0    | 1    | 2    |
| Feat2 | 1    | 2    | 3    |
| Feat3 | 2    | 3    | 4    |

When rendered, they will take the full width of the page:

  Obs1 Obs2 Obs3
Feat1 0 1 2
Feat2 1 2 3
Feat3 2 3 4

This does not appear to be visually appealing when representing matrices, which is why a matrix box can be used instead:

> |       | Obs1 | Obs2 | Obs3 |
> | ----- |--------------------|
> | Feat1 | 0    | 1    | 2    |
> | Feat2 | 1    | 2    | 3    |
> | Feat3 | 2    | 3    | 4    |
{: .matrix}

The rendered table is then given as a minimum-width and centred matrix:

  Obs1 Obs2 Obs3
Feat1 0 1 2
Feat2 1 2 3
Feat3 2 3 4

Improving the learning experience

To improve the learning experience in our tutorial, we define some boxes to highlight content.

These boxes are defined always with the same structure:

> ### {% icon an_icon %} Type of box: Name of the box
> list
{: .type_of_box}

You must follow this structure exactly for it to be rendered correctly.

Overview box

This box at the top of each tutorial is automatically generated using the metadata we defined in the topic’s metadata file:

Overview

question Questions

  • Which biological questions are addressed by the tutorial?
  • Which bioinformatics techniques are important to know for this type of data?

objectives Objectives

  • The learning objectives are the goals of the tutorial
  • They will be informed by your audience and will communicate to them and to yourself what you should focus on during the course
  • They are single sentences describing what a learner should be able to do once they have completed the tutorial
  • You can use Bloom’s Taxonomy to write effective learning objectives

requirements Requirements

time Time estimation: ‘1H’

hands_on Hands-on: Checking the metadata

  1. Check that the metadata added previously are correctly filling the overview box

    question Questions

    What metadata hasn’t been added to this box?

    solution Solution

    The take-home messages are not added to this box but into the last box of the tutorial

Agenda box

In most tutorials, the second box is the agenda box, placed at the end of the introduction. It shows the table of contents for the tutorial

> ### Agenda
>
> In this tutorial we will deal with:
>
> 1. TOC
> {:toc}
>
{: .agenda}

There is no need to fill out the list; this will be done automatically based off of your tutorial’s section title.

To avoid adding the “Introduction” and “Conclusion” sections in the agenda, you can add {:.no_toc} below the section name. This will be rendered as follows:

Agenda

In this tutorial we will deal with:

  1. TOC

Hands-on box

We find that having users walk through the tutorial, doing all of the steps is important for learning the concepts taught. We therefore emphasize this by regularly adding hands-on sections, where trainees are encouraged to do the analysis by themselves. We have designed some special boxes to make these sections easier to find.

> ### {% icon hands_on %} Hands-on: Spliced mapping
>
> 1. **RNA STAR** {% icon tool %}: Map your reads on the reference genome with
>    - *"Single-end or paired-end reads"*:  `Paired-end (as individual datasets)`
>    - *"RNA-Seq FASTQ/FASTA file, forward reads"*: the generated `trimmed reads pair 1` files (multiple datasets)
>    - *"RNA-Seq FASTQ/FASTA file, reverse reads"*: the generated `trimmed reads pair 2` files (multiple datasets)
>    - *"Custom or built-in reference genome"*: `Use a built-in index`
>    - *"Reference genome with or without an annotation"*: `use genome reference without builtin gene-model`
>    - *"Select reference genome"*: `Drosophila Melanogaster (dm6)`
>    - *"Gene model (gff3,gtf) file for splice junctions"*: the imported `Drosophila_melanogaster.BDGP6.87.gtf`
>    - *"Length of the genomic sequence around annotated junctions"*: `36`
>
>        This parameter should be length of reads - 1
>
> 2. {% tool [MultiQC](toolshed.g2.bx.psu.edu/repos/iuc/multiqc/multiqc/1.8+galaxy0) %}: Aggregate the STAR logs with
>      - *"Which tool was used generate logs?"*: `STAR`
>      - *"Type of FastQC output?"*: `Log`
>      - *"STAR log output"*: the generated `log` files (multiple datasets)
{: .hands_on}

For consistency please use:

  • {% icon hands_on %} icon to define that is an hands-on
  • Short imperative sentences to make it easy to identify the tasks
  • Name of the tool in bold followed by {% icon tool %} icon to make it easy to identify a Galaxy tool
  • Parameters for the tool as a sublist

This will be rendered like:

hands_on Hands-on: Spliced mapping

  1. RNA STAR tool: Map your reads on the reference genome with
    • “Single-end or paired-end reads: Paired-end (as individual datasets)
    • RNA-Seq FASTQ/FASTA file, forward reads: the generated trimmed reads pair 1 files (multiple datasets)
    • RNA-Seq FASTQ/FASTA file, reverse reads: the generated trimmed reads pair 2 files (multiple datasets)
    • “Custom or built-in reference genome”: Use a built-in index
    • “Reference genome with or without an annotation”: use genome reference without builtin gene-model
    • “Select reference genome”: Drosophila Melanogaster (dm6)
    • “Gene model (gff3,gtf) file for splice junctions”: the imported Drosophila_melanogaster.BDGP6.87.gtf
    • “Length of the genomic sequence around annotated junctions”: 36

      This parameter should be length of reads - 1

  2. MultiQC Tool: toolshed.g2.bx.psu.edu/repos/iuc/multiqc/multiqc/1.8+galaxy0 : Aggregate the STAR logs with
    • “Which tool was used generate logs?”: STAR
    • “Type of FastQC output?”: Log
    • “STAR log output”: the generated log files (multiple datasets)

There are also some predefined parameter icons available which can be used to indicate the type of parameter. These are optional, but may be helpful in some cases (for example to distinguish between single file inputs and collection inputs).

The available icons are:

> ### {% icon hands_on %} Hands-on: My Step
>
> 1. **My Tool** {% icon tool %} with the following parameters
>    - {% icon param-text %} *"My text parameter"*: `my value`
>    - {% icon param-file %} *"My input file"*: `my file`
>    - {% icon param-files %} *"My multiple file input or collection"*: `my collection`
>    - {% icon param-select %} *"My select menu"*: `my choice`
>    - {% icon param-check %} *"My check box"*: `yes`
>    - {% icon param-repeat %} **My repeat parameter**
>      - *"param1"*: `42`
{: .hands_on}

which, when rendered, look like:

hands_on Hands-on: My Step

  1. My Tool tool with the following parameters
    • param-text “My text parameter”: my value
    • param-file “My input file”: my file
    • param-files “My multiple file input or collection”: my collection
    • param-select “My select menu”: my choice
    • param-check “My check box”: yes
    • param-repeat My repeat parameter
      • “param1”: 42

With the new GTN in Galaxy Webhook, trainees can view training directly within Galaxy. As part of this, we enable those trainees to click on tools, and have those tools directly activated in Galaxy, enabling for a seamless training experience for trainees.

GIF of a user using the GTN in Galaxy webhook.
Figure 3: A gif showing how the GTN in Galaxy webhook works. A student clicks the learning hat icon in the masthead of a Galaxy server, and an overlay is activated showing the GTN website. Within the GTN they can browse around and their place in tutorials is saved. While following a tutorial the student reches a step which instructs them to run a specific tool. Instead of the normal experience searching for a tool (quite difficult on large servers), they click a blue button and the tool is activated in Galaxy, and the overlay is closed. The student can reactivate the overlay at any time and return to their place in the tutorial.

To enable these in your tutorial you can use the following syntax:

- {% tool MultiQC %}
- {% tool [MultiQC](toolshed.g2.bx.psu.edu/repos/iuc/multiqc/multiqc/1.8+galaxy0) %}
- {% tool [Import some data](upload1) %}

Which will be rendered as:

  • MultiQC
  • MultiQC Tool: toolshed.g2.bx.psu.edu/repos/iuc/multiqc/multiqc/1.8+galaxy0
  • Import some data Tool: upload1

When viewed through Galaxy, students will see:

Import some data Tool: upload1

How to find these IDs?

The easiest way is to use planemo to generate the training from a workflow. In recent versions of planemo, this is managed automatically.

The alternative is to figure out the ID for the tool you want to use:

  1. Find your tool in Galaxy, and click to access the tool form.
  2. Click on Options at the top right
  3. Click on Share
  4. The URL shown will be something like https://usegalaxy.eu/root?tool_id=toolshed.g2.bx.psu.edu/repos/galaxyp/mz_to_sqlite/mz_to_sqlite/2.0.4+galaxy1
  5. Keep only the part after the =, so toolshed.g2.bx.psu.edu/repos/galaxyp/mz_to_sqlite/mz_to_sqlite/2.0.4+galaxy1 in this example

Finding the tool ID.

Questions and solution boxes

Questions can be added to force trainees to think about what they are currently doing, and to put things in perspective. They can also help the instructors by exposing and clarifying common scenarios, errors, or applications.

> ### {% icon question %} Questions
>
> 1. Why are some tests filtered?
> 2. Does it improve the *p*-value distribution?
>
> > ### {% icon solution %} Solution
> >
> > 1. Sol for the first question
> > 2. Sol for the second question
> >
> {: .solution}
{: .question}

Which will be rendered as:

question Questions

  1. Why are some tests filtered?
  2. Does it improve the p-value distribution?

solution Solution

  1. Sol for the first question
  2. Sol for the second question

Questions should be quick to answer. You can directly ask a question and expect an answer, or you can provide some answers and create multiple choices questions (MCQs). With well chosen wrong answers, MCQs can do much more than just measure how much someone knows, such as exposing common misconceptions and mistakes.

In the box below, initially hidden, we add the correct answer and possibly any additional explanation. Self-trainees can then check the solution and its explanation.

Tips box

Tips boxes are really just for ‘tips’, usually hints regarding Galaxy operations that users may or may not be familiar with. If you want to provide extended discussion or links to external materials then consider the comment and detail boxes instead.

> ### {% icon tip %} Tip: Importing data via links
>
> * Copy the link location
> * Open the Galaxy Upload Manager
> * Select **Paste/Fetch Data**
> * Paste the link into the text field
> * Press **Start**
{: .tip}

Rendered:

  • Copy the link location
  • Open the Galaxy Upload Manager
  • Select Paste/Fetch Data
  • Paste the link into the text field
  • Press Start

Comments boxes

> ### {% icon comment %} Comments
> - Edit the "Database/Build" to select "dm3"
> - Rename the datasets according to the samples
{: .comment}

Rendered:

comment Comments

  • Edit the “Database/Build” to select “dm3”
  • Rename the datasets according to the samples

Details box

The detail box is used to give more background explanation on the subject. By default the box is collapsed, trainees can expand it if they wish to know extra information about a topic.

> ### {% icon details %} More details on the ....
>
> Add more details in Markdown...
>
{: .details}

Rendered:

details More details on the ….

Add more details in Markdown…

Key points box

This last box of the tutorial is automatically created with the take-home messages defined in the topic’s metadata

To render the boxes correctly, the syntax needs to be correct. If it doesn’t work, have a look at similar tutorials and get inspiration.

Warning box

> ### {% icon warning %} Danger: You can lose data!
> Something really bad can happen here!
{: .warning}

Rendered:

warning Danger: You can lose data!

Something really bad can happen here!

Nested boxes

Boxes can be nested, e.g. for having tips inside a hands-on:

> ### {% icon hands_on %} Hands-on: Defining the topic for the tutorial
>
> 1. Search for NCBI Blast+ on the [ToolShed](https://toolshed.g2.bx.psu.edu/)
> 2. Check in which category it is
>
>    > ### {% icon question %} Questions
>    >
>    > In which topic will you put the tutorial?
>    >
>    > > ### {% icon solution %} Solution
>    > >
>    > > If we search for [NCBI Blast+ in the ToolShed](https://toolshed.g2.bx.psu.edu/view/devteam/ncbi_blast_plus/7538e2bfcd41), it is attributed to 2 categories (bottom): "Next Gen Mappers" and "Sequence Analysis".
>    > > We decided to put it in "Sequence analysis" because this is the most general one for this tutorial.
>    > {: .solution}
>    {: .question}
{: .hands_on}

Code box

We have added code in/out boxes to help you show commands, and their effects, when running command line commands.

Normally a single column, with the boxes above one another, it will automatically split side-by-side over a given width (1200px);

> > ### {% icon code-in %} Input: Bash
> > ```bash
> > cat /tmp/test.ini
> > ```
> {: .code-in}
>
> > ### {% icon code-out %} Output
> > The file should look like:
> >
> > ```ini
> > [example]
> > server_name = Dogs!
> > listen = 192.168.0.2
> > apikey = super-secret-api-key-wow!
> > ```
> {: .code-out}
{: .code-2col}

Rendered (try it! resize your browser)

code-in Input: Bash

cat /tmp/test.ini

code-out Output

The file should look like:

[example]
server_name = Dogs!
listen = 192.168.0.2
apikey = super-secret-api-key-wow!

If you leave off the {: .code-2col}, it will render as a single column always.

> ### {% icon code-in %} Input: Bash
> ```bash
> cat /tmp/test.ini
> ```
{: .code-in}

> ### {% icon code-out %} Output
> The file should look like:
>
> ```ini
> [example]
> server_name = Dogs!
> listen = 192.168.0.2
> apikey = super-secret-api-key-wow!
> ```
{: .code-out}

Rendered:

code-in Input: Bash

cat /tmp/test.ini

code-out Output

The file should look like:

[example]
server_name = Dogs!
listen = 192.168.0.2
apikey = super-secret-api-key-wow!

FAQs (snippets)

Many common questions or instructions may be useful to share between different tutorials. For example instructions on how to start a new history or importing data. To make these types of snippets easier to re-use and avoid duplication, they are available in the form of snippets.

Finding snippets

These are available in folders named faqs, either at the project level, topic level, or tutorial level.

  • Project-level FAQs: faqs/
    • faqs/galaxy/ for general Galaxy questions
    • faqs/gtn/ for questions regarding the GTN website itself
  • Topic-level FAQs: topics/<topic>/faqs/
    • for questions pertaining to that specific topic
  • Tutorial-level FAQs: topics/<topic>/tutorials/<tutorial>/faqs/
    • for questions pertaining to that specific tutorial
    • if this is present, it is linked to from the tutorial overview box at the top, and from the end of the tutorial

Including FAQs/snippets in your tutorials

To include one of these snippets in your tutorial, you can use the following syntax:

{% snippet faqs/galaxy/histories_create_new.md %}

Which will be rendered as:

Tip: Creating a new history

Click the new-history icon at the top of the history panel.

If the new-history is missing:

  1. Click on the galaxy-gear icon (History options) on the top of the history panel
  2. Select the option Create New from the menu

The advantage of this approach is that when the Galaxy interface updates, we only have to update the snippet, rather than every tutorial. Please try to use snippets whenever you can!

You could also specify the box type you want the snippet to be rendered in:

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

Hands-on: Creating a new history

Click the new-history icon at the top of the history panel.

If the new-history is missing:

  1. Click on the galaxy-gear icon (History options) on the top of the history panel
  2. Select the option Create New from the menu

or without a box altogether:

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

Click the new-history icon at the top of the history panel.

If the new-history is missing:

  1. Click on the galaxy-gear icon (History options) on the top of the history panel
  2. Select the option Create New from the menu

Creating new FAQs/snippets

Do you want to include something in your tutorial that you think might be useful in other tutorials as well? Or are you answering a frequently asked question? Consider creating a snippet for it

Each snippet (question) is a separate file, with some metadata, residing in one of the faqs folders:

---
title: How do I run a workflow?
area: workflows      # FAQs will be grouped by these areas on the FAQ page
box_type: tip        # tip/comment/hands_on/question; optional, if you want the content to be in a box
layout: faq          # if you set this the snippet will get its own page and be included in the FAQs page
contributors: [annefou,nomadscientist] # anybody who has contributed to the FAQ over time
---

Here you can write the snippet / answer to the FAQ in Markdown

- Go to `Workflows` on the top menu bar
- Click on ..
- ..

FAQ pages

All FAQs will also be collected on their own page, this makes it easy for and teachers to prepare the session, and for participants to quickly find the answers to common questions.

To do this, create a file named index.md inside the faq folder:

---
layout: faq-page
---

If you would like to enforce an order of the faq areas, you can do so:

---
layout: faq-page
area_order: [introduction, learners, instructors, contributors, other]
---

(just make sure you list all existing areas in the folder)

If a tutorial-level FAQ page exists (topics/<topic>/tutorials/<tutorial>/faqs/index.md) it will be automatically linked to from the overview box at the top of the tutorial, and at the end of the tutorial. Have a look at this tutorial to see it in action.

Footnotes

code-in Input: Markdown

Footnotes[^1] can be used to insert more content or explanation as reference material to your content. You can use the same footnote reference multiple time, and the footnote will include backlinks to return to the correct place in the text.[^1]

code-out Output

Footnotes1 can be used to insert more content or explanation as reference material to your content. You can use the same footnote reference multiple time, and the footnote will include backlinks to return to the correct place in the text.1

Icons

To use these icons, take the name of the icon, ‘details’ in this example, and write something like this in your tutorial:

{% icon details %}
icon[0]
announcement
icon[0]
code-in
icon[0]
code-out
icon[0]
cofest
icon[0]
comment
icon[0]
congratulations
icon[0]
curriculum
icon[0]
details
icon[0]
docker_image
icon[0]
email
icon[0]
exchange
icon[0]
event
icon[0]
feedback
icon[0]
galaxy-barchart
icon[0]
galaxy-bug
icon[0]
galaxy-chart-select-data
icon[0]
galaxy-clear
icon[0]
galaxy-columns
icon[0]
galaxy-cross
icon[0]
galaxy-dropdown
icon[0]
galaxy-eye
icon[0]
galaxy-gear
icon[0]
galaxy-history
icon[0]
galaxy-home
icon[0]
galaxy-info
icon[0]
galaxy-library
icon[0]
galaxy-link
icon[0]
galaxy-panelview
icon[0]
galaxy-pencil
icon[0]
galaxy-refresh
icon[0]
galaxy-rulebuilder-history
icon[0]
galaxy-save
icon[0]
galaxy-scratchbook
icon[0]
galaxy-selector
icon[0]
galaxy-star
icon[0]
galaxy-tags
icon[0]
galaxy-toggle
icon[0]
galaxy-upload
icon[0]
galaxy-wf-connection
icon[0]
galaxy-wf-new
icon[0]
galaxy-wf-report-download
icon[0]
galaxy_instance
icon[0]
github
icon[0]
gitter
icon[0]
gtn-theme
icon[0]
hall-of-fame
icon[0]
hands_on
icon[0]
help
icon[0]
history-annotate
icon[0]
history-share
icon[0]
instances
icon[0]
interactive_tour
icon[0]
keypoints
icon[0]
language
icon[0]
last_modification
icon[0]
level
icon[0]
license
icon[0]
linkedin
icon[0]
new-history
icon[0]
notebook
icon[0]
objectives
icon[0]
orcid
icon[0]
param-check
icon[0]
param-collection
icon[0]
param-file
icon[0]
param-files
icon[0]
param-repeat
icon[0]
param-select
icon[0]
param-text
icon[0]
question
icon[0]
references
icon[0]
requirements
icon[0]
rss-feed
icon[0]
search
icon[0]
slides
icon[0]
solution
icon[0]
sticky-note
icon[0]
time
icon[0]
text-document
icon[0]
tip
icon[0]
tool
icon[0]
tool-versions
icon[0]
topic
icon[0]
trophy
icon[0]
tutorial
icon[0]
twitter
icon[0]
warning
icon[0]
wf-input
icon[0]
workflow-runtime-toggle
icon[0]
workflow
icon[0]
workflow-run
icon[0]
video
icon[0]
video-slides
icon[0]
zenodo_link

Abbreviations

Oftentimes there are terms you’ll use over and over again where there is an acronym or abbreviation you’ll use consistently. However for learners new to the material, they might need to scroll up to the first definition every time to remember what it meant. It would be annoying as an author to have to re-define it every time, so we’ve implemented some very simple syntax to allow you to create a list of definitions and then use those in the text.

In your tutorial metadata you can add an abbreviations section like:

---
title: My awesome tutorial
...
abbreviations:
  API: Application Programming Interface
  JSON: JavaScript Object Notation
---

And in your text you can use braces to refer to the term

code-in Input: Markdown

The `/jobs` {API} will return {JSON}. When we call the {API} we'll get back this result {JSON}.

code-out Output

The /jobs Application Programming Interface (API) will return JavaScript Object Notation (JSON). When we call the API we’ll get back this result JSON.

Choose Your Own Tutorial

Sometimes you’re writing a large tutorial and at one small step there are multiple paths or multiple ways to get the data you want, and you’d like to showcase them all! You could write them all out in order, Option 1…2…etc, however maybe you want it to be a bit more interactive and focus only on one option at a time, so a user doesn’t get distracted by the other options.

Include this markdown where you want your user to choose between the multiple paths:

code-in Input: Markdown

{% include _includes/cyoa-choices.html option1="Ananas" option2="Avocados" default="Avocados"
       text="Here is why some people choose Ananas. Other times you want Avocados as they fit the menu better." %}

hands_on Hands-on: Choose Your Own Tutorial

This is a "Choose Your Own Tutorial" section, where you can select between multiple paths. Click one of the buttons below to select how you want to follow the tutorial

Here is why some people choose Ananas. Other times you want Avocados as they fit the menu better.

And then they can wrap the relevant sections with a div block with the relevant class. You must set markdown="1" as well to have the inner contents rendered corretly.

NB: If you do not set a default, then on the very first page load, both options will be shown in their entirety. As soon as the user selects one of the options by clicking the relevant button, then the list is filtered. The user’s browser generally will remember which button was selected across navigation and page reloads.

code-in Input: Markdown

<div class="Ananas" markdown="1">
- 🍍 are fantastic
- hands on!
- questions!
- solutions!
</div>
<div class="Avocados" markdown="1">
- 🥑 are amazing
- hands on!
- questions!
- solutions!
</div>

code-out Output

  • 🍍 are fantastic
  • hands on!
  • questions!
  • solutions!
  • 🥑 are amazing
  • hands on!
  • questions!
  • solutions!

This can also be used inline: My favourite fruit is an 🍍🥑.

URL Parameter

The branch can be selected via URL parameter e.g. for courses, to prevent users selecting the wrong path. Just supply ?gtn-cyoa=Ananas (or your preferred value) on the tutorial URL.

Citations

If you would like to cite any articles, books or websites in your tutorial, you can do so by adding a file called tutorial.bib next to your tutorial.md file. In this file you may enter bibtex formatted citations. An example is given below:

@article{bebatut2018community,
  title={Community-driven data analysis training for biology},
  author={Batut, B{\'e}r{\'e}nice and Hiltemann, Saskia and Bagnacani, Andrea and Baker, Dannon and Bhardwaj, Vivek and Blank, Clemens and Bretaudeau, Anthony and Brillet-Gu{\'e}guen, Loraine and {\v{C}}ech, Martin and Chilton, John and others},
  journal={Cell systems},
  volume={6},
  number={6},
  pages={752--758},
  year={2018},
  publisher={Elsevier},
  doi={10.1016/j.cels.2018.05.012}
}

@misc{galaxy-training-materials,
  url = {https://training.galaxyproject.org},
  note = {Accessed 2019-04-08},
  title = {Galaxy Training materials website}
}

@online{Galaxy-P_Metaproteomics,
  author = {Galaxy-P Team},
  title = {Galaxy-P Metaproteomics instance},
  url = {https://proteomics.usegalaxy.eu/},
  urldate = {2020-10-13}
}

You can use this in your tutorial as follows:

For more information please look at this great article {% cite bebatut2018community %},
and the corresponding website {% cite galaxy-training-materials %}

Rendered:

For more information please look at this great article Batut et al. 2018, and the corresponding website Galaxy Training materials website

A bibliography will automatically be appended to the end of your tutorial (scroll down to the end of this tutorial to see how it looks! or jump there directly)

tip Tip: Getting a bibtex citation from a doi

If you have a DOI for a paper, you can easily obtain the bibtex citation using doi2bib.org.

Automatic Jupyter Notebooks & RMarkdown

If your tutorial is primarily focused on teaching students how to write code (Bash, Python, SQL, etc) you can take advantage of the GTN’s ability to automatically export notebooks from the tutorial content! In this system, you pick a single language for your tutorial, and then all code blocks tagged with that language become runnable. E.g.

Here is some explanation

```python
some_code += f"that students {should execute}"
```

Currently Supported Languages

Language Jupyter RMarkdown
Bash Yes No
SQL Yes No
R Yes Yes
Python Yes No

Every cell that you wish to be executable, needs to be annotated with the language like above. Then if a compatible notebook can be produced, it will be.

Restrictions

To use this system, you need to take care of a few things:

  • Do not use hands-on boxes for segments that should be executed (code needs to be left aligned!)
  • Do not use snippets
  • Do not use a terminal or prompt character (that would be included in the execution.)
  • Avoid including output when you can, it doesn’t render nicely especially when the cells will become runnable.

And be aware that the output will look a little bit different than the GTN, e.g. solution boxes cannot be hidden by default, so in Jupyter notebook we format the text with a colour of white so it does not appear in the notebook and requires selection to view the answer.

However there are things that are possible! You can still use question/solution boxes, or otherwise nested boxes. Just not includes or snippets

Enabling the system

Add metadata to your tutorial.md header like:

notebook:
  language: python

Supported values are python, sql, r, and bash. The notebook will be generated automatically as part of the site build process.

JupyterLite & Pyodide

The GTN has support for JupyterLite and the Pyodide kernel which runs Python in the browser via webassembly/javascript. This comes with some restrictions:

  • Python only2
  • No filesystem access (so no wget prep steps)
  • Little to no cell magic

However, it means we can run a lot of our Python training directly in the GTN! And in the future, hopefully, we will be able to embed individual cells of the notebook directly in the Python training, so the user doesn’t even need to switch pages.

To enable this feature, set:

notebook:
  language: python
  pyolite: true

Spanish Translation Project

We have started a trial for translating tutorials into Spanish. Below are instructions on how to add translations of slides and/or hands-on tutorials in Spanish.

  1. Add a new file with the translated material, next to the English version.
    • Add suffix _ES suffix
      • i.e. tutorial_ES.md or slides_ES.html
  2. Add metadata to the English version (at the top of the file):
      tags:
        - español
      translations:
        - es
    
  3. Add metadata to the translated version of the file:
      lang: es
      translations:
        - en
    

If all worked well, it should look something like this, with a dropdown menu on the slides and/or tutorial showing the presence of a curated tutorial:

example of the view in the topic page for a tutorial with a Spanish translation.

Other Languages

Would you like to add a different language to the GTN? Please contact us first (e.g. on Gitter), to discuss a long-term sustainability plan!

Conclusion

Footnotes (Rendered)

  1. The wikipedia definition of a footnote is: “A note is a string of text placed at the bottom of a page in a book or document or at the end of a chapter, volume or the whole text. The note can provide an author’s comments on the main text or citations of a reference work in support of the text. Footnotes are notes at the foot of the page while endnotes are collected under a separate heading at the end of a chapter, volume, or entire work. Unlike footnotes, endnotes have the advantage of not affecting the layout of the main text, but may cause inconvenience to readers who have to move back and forth between the main text and the endnotes.”  2

  2. Not entirely true, other kernels are supported, see their demo repo, but e.g. the SQLite kernel comes with severe restrictions like no downloading databases or connecting to ones online. 

Key points

  • You can highlight questions, tools and hints with a special syntax

  • Self-learning can be done by questions and hidden answers

Frequently Asked Questions

Have questions about this tutorial? Check out the tutorial FAQ page or the FAQ page for the Contributing to the Galaxy Training Material topic to see if your question is listed there. If not, please ask your question on the GTN Gitter Channel or the Galaxy Help Forum

References

  1. Galaxy Training materials website. Accessed 2019-04-08. https://training.galaxyproject.org
  2. Batut, B., S. Hiltemann, A. Bagnacani, D. Baker, V. Bhardwaj et al., 2018 Community-driven data analysis training for biology. Cell systems 6: 752–758. 10.1016/j.cels.2018.05.012

Glossary

API
Application Programming Interface
JSON
JavaScript Object Notation

Feedback

Did you use this material as an instructor? Feel free to give us feedback on how it went.
Did you use this material as a learner or student? Click the form below to leave feedback.

Click here to load Google feedback frame

Citing this Tutorial

  1. Bérénice Batut, Björn Grüning, Saskia Hiltemann, Helena Rasche, 2022 Creating content in Markdown (Galaxy Training Materials). https://training.galaxyproject.org/training-material/topics/contributing/tutorials/create-new-tutorial-content/tutorial.html Online; accessed TODAY
  2. Batut et al., 2018 Community-Driven Data Analysis Training for Biology Cell Systems 10.1016/j.cels.2018.05.012

details BibTeX

@misc{contributing-create-new-tutorial-content,
author = "Bérénice Batut and Björn Grüning and Saskia Hiltemann and Helena Rasche",
title = "Creating content in Markdown (Galaxy Training Materials)",
year = "2022",
month = "05",
day = "19"
url = "\url{https://training.galaxyproject.org/training-material/topics/contributing/tutorials/create-new-tutorial-content/tutorial.html}",
note = "[Online; accessed TODAY]"
}
@article{Batut_2018,
    doi = {10.1016/j.cels.2018.05.012},
    url = {https://doi.org/10.1016%2Fj.cels.2018.05.012},
    year = 2018,
    month = {jun},
    publisher = {Elsevier {BV}},
    volume = {6},
    number = {6},
    pages = {752--758.e1},
    author = {B{\'{e}}r{\'{e}}nice Batut and Saskia Hiltemann and Andrea Bagnacani and Dannon Baker and Vivek Bhardwaj and Clemens Blank and Anthony Bretaudeau and Loraine Brillet-Gu{\'{e}}guen and Martin {\v{C}}ech and John Chilton and Dave Clements and Olivia Doppelt-Azeroual and Anika Erxleben and Mallory Ann Freeberg and Simon Gladman and Youri Hoogstrate and Hans-Rudolf Hotz and Torsten Houwaart and Pratik Jagtap and Delphine Larivi{\`{e}}re and Gildas Le Corguill{\'{e}} and Thomas Manke and Fabien Mareuil and Fidel Ram{\'{\i}}rez and Devon Ryan and Florian Christoph Sigloch and Nicola Soranzo and Joachim Wolff and Pavankumar Videm and Markus Wolfien and Aisanjiang Wubuli and Dilmurat Yusuf and James Taylor and Rolf Backofen and Anton Nekrutenko and Björn Grüning},
    title = {Community-Driven Data Analysis Training for Biology},
    journal = {Cell Systems}
}
                

Congratulations on successfully completing this tutorial!

Developing GTN training material

This tutorial is part of a series to develop GTN training material, feel free to also look at:
  1. Overview of the Galaxy Training Material
  2. Adding auto-generated video to your slides
  3. Adding Quizzes to your Tutorial
  4. Contributing with GitHub via command-line
  5. Contributing with GitHub via its interface
  6. Creating a new tutorial
  7. Creating content in Markdown
  8. Creating Interactive Galaxy Tours
  9. Creating Slides
  10. Generating PDF artefacts of the website
  11. Including a new topic
  12. Running the GTN website locally
  13. Running the GTN website online using GitPod
  14. Tools, Data, and Workflows for tutorials
  15. Updating diffs in admin training