Merge pull request #5507 from galaxyproject/tutorialmodefaq

Add an FAQ to explain how to prepare a tutorial to support tutorial mode

faqs/gtn/gtn_event_create.md

@@ -30,7 +30,7 @@ For a full list of metadata fields for events, please have a look at our [schema
 Please also feel free to contact us with ideas for improvements! We know that training comes in many different forms, so if something in your event is not yet supported, let us know and we are happy to add it!
 
 
-## External events
+### External events
 
 Already have a course webpage? Great! In this case, you only have to provide the most basic information about your course (title, desciption, dates, location).
 

faqs/gtn/gtn_tutorial_mode.md

@@ -0,0 +1,50 @@
+---
+title: Supporting Tutorial Mode (GTN-in-Galaxy) in a tutorial
+area: contributors
+layout: faq
+box_type: tip
+contributors: [shiltemann]
+---
+
+GTN tutorials can be viewed directly within Galaxy, we call this *Tutorial mode* ([read news post]({% link faqs/galaxy/tutorial_mode.md %}))
+
+In this mode, tool names in hands-on boxes become clickable, directly opening the tool in Galaxy, at the right version.
+
+To enable this feature, a bit of metadata needs to be added to the tool names in hands-on boxes as follows:
+
+{% raw %}
+```
+{% tool [Name](Toolshed ID) %}
+```
+{% endraw %}
+
+For example:
+
+{% raw %}
+```
+{% tool [bedtools intersect intervals](toolshed.g2.bx.psu.edu/repos/iuc/bedtools/bedtools_intersectbed/2.30.0+galaxy1) %}
+```
+{% endraw %}
+
+To find the toolshed ID of a tool:
+
+1. Open the tool in Galaxy
+2. Click on the {% icon dropdown %} options menu (dropdown icon)
+3. Select **Copy Tool ID**
+
+  ![screenshot of menu with toolshed link for a tool]({% link faqs/gtn/images/tool_toolshed_link.png %})
+
+Example of a hands-on box using this feature:
+
+{% raw %}
+```
+> <hands-on-title> Counting SNPs </hands-on-title>
+>
+> 1. {% tool [Datamash](toolshed.g2.bx.psu.edu/repos/iuc/datamash_ops/datamash_ops/1.8+galaxy0) %} (operations on tabular data):
+>
+>    - *"Input tabular dataset"*: select the output dataset from **bedtools intersect intervals** {% icon tool %}
+>    - *"Group by fields"*: `Column: 4` (the column with the exon IDs)
+>
+{: .hands_on}
+```
+{% endraw %}

faqs/gtn/gtn_workflow_testing.md

@@ -6,7 +6,7 @@ box_type: tip
 contributors: [hexylena]
 ---
 
-## Ensuring a Tutorial has a Workflow
+### Ensuring a Tutorial has a Workflow
 
 1. Find a tutorial that you're interested in, that **doesn't currently have tests.**
 
@@ -24,13 +24,13 @@ contributors: [hexylena]
 4. Extract a workflow from the history
 5. Run that workflow in a new history to test
 
-## Extract Tests (Online Version)
+### Extract Tests (Online Version)
 
 If you are on UseGalaxy.org or another server running 24.2 or later, you can use [PWDK](https://pwdk.apps.galaxyproject.eu/), a version of planemo running online to generate the workflow tests.
 
 However if you are on an older version of Galaxy, or a private Galaxy server, then you'll need to do the following:
 
-## Extract Tests (Manual Version)
+### Extract Tests (Manual Version)
 
 6. Obtain the workflow invocation ID, and your API key (User → Preferences → Manage API Key)
 
@@ -61,7 +61,7 @@ However if you are on an older version of Galaxy, or a private Galaxy server, th
    └── testing-openlayer-tests.yml
    ```
 
-## Adding Your Tests to the GTN
+### Adding Your Tests to the GTN
 
 9. You will need to check the `-tests.yml` file, it has some automatically generated comparisons. Namely it tests that output data matches the test-data exactly, however, you might want to replace that with assertions that check for e.g. correct file size, or specific text content you expect to see.
 

faqs/gtn/my-galaxy-training.md

@@ -10,21 +10,21 @@ The [`my.galaxy.training`](https://my.galaxy.training) is part of the GTN. We fo
 
 E.g. how do we link to [/user](https://my.galaxy.training/?path=/user), the user preferences page which is available on every Galaxy Instance? This service handles that in a private and user-friendly manner.
 
-## (Learners) How to Use It
+### (Learners) How to Use It
 
-When you access a my.galaxy.training page you'll be prompted to select a server, simply select one and you're good to go! 
+When you access a my.galaxy.training page you'll be prompted to select a server, simply select one and you're good to go!
 
 If you want to enter a private Galaxy instance, perhaps, behind a firewall, that's also an option! Just select the 'other' option and provide your domain. Since the redirection happens in your browser with no servers involved, as long as *you* can access the server, you'll get redirected to the right location.
 
-## (Tutorial Authors) How to use it
+### (Tutorial Authors) How to use it
 
 If you want to link to a specific page within Galaxy, simple construct the URL: `https://my.galaxy.training/?path=/user` where everything after `?path` is the location they should be redirected to on Galaxy. That example link will eventually redirect the learner to something like `https://usegalaxy.eu/user`.
 
-## Technical Background
+### Technical Background
 
 So we took inspiration from [Home Assistant](https://my.home-assistant.io/) which had the same problem, how to redirect users to pages on their own servers. The `my.galaxy.training` service is a very simple static page which looks in the user's [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) for their preferred server.
 If it's not set, the user can click one of the common domains, and be redirected. When they access another link, they'll be prompted to use a button that remembers which server they chose.
 
-## Data Privacy
+### Data Privacy
 
 Any domain selected is not tracked nor communicated to any third party. Your preferred server is stored in your browser, and never transmitted to the GTN. That's why we use localStorage instead of cookies.

faqs/gtn/why-the-gtn.md

@@ -8,20 +8,20 @@ contributors: [hexylena]
 
 The short version is we're a popular, FAIR training materials platform, and we want to be a home for your training materials.
 
-## Your content in front of the world
+### Your content in front of the world
 
 As of June 2023 the GTN sees around 60k visitors per month. Please see [our public page view monitoring](https://plausible.galaxyproject.eu/training.galaxyproject.org?period=30d) for more details.
 
-## FAIR
+### FAIR
 
 We go to great lengths to make sure our training platform is completely FAIR. See [this FAQ for the details on how we achieve that.]({% link faqs/gtn/fair_training.md %}). All of our materials have extensive [BioSchemas](https://bioschemas.org) markup ensuring they're easily accessible to search engines.
 Our materials are automatically indexed by [TeSS](https://tess.elixir-europe.org/materials?content_provider=Galaxy+Training), and we are working on a WorkflowHub integration.
 
-## Accessible
+### Accessible
 
 We regularly test our pages with a thorough suite of accessibility tools, as well as via screen reader.
 
-## Not Just Galaxy
+### Not Just Galaxy
 
 Our name can be a bit misleading! While a lot of our tutorials are focused on Galaxy, we have multiple growing topics which are unrelated to Galaxy.
 
@@ -31,7 +31,7 @@ Our name can be a bit misleading! While a lot of our tutorials are focused on Ga
 
 All of these topics are using the GTN as a platform to disseminate their materials far and wide.
 
-## Features
+### Features
 
 Do you need