Skip to content

Creating New Topics and Tutorials

Cory Maughmer edited this page Dec 2, 2020 · 1 revision

Creating Hands-On Tutorials

Create New Topic

  1. Create a new directory in the 'topics' directory named <topic name>. This should be all lowercase and replace spaces with "-".
  2. Copy the templates/ directory contents into topics/<topic name> directory, you can delete the copied README.md file.
  3. Create a symlinked file to the topic's metadata file in the metadata directory with ln -s topics/metadata.yaml metadata/<topic name>.yaml. This should be done on a Linux command line and run from the repository root.
  4. Update the topics/<topic name>/metadata.yaml header and maintainers information with the proper information.
    • name is the lowercase/no spaces version that matches the directory name chosen above
    • title is the human readable version to be displayed in the site content.
    • Names listed under maintainers: should be github usernames that match an entry in the CONTRIBUTORS.yaml file in the repository root.
    • Indentation is important in yaml
    name: "Name of the topic"
    type: "use"
    title: "topic_name"
    summary: "Description of the topic"
    requirements:
      -
        title: "Galaxy introduction"
        type: "internal"
        link: "/introduction/"
    maintainers:
      - <github username>
  5. Place any tutorial files into the topics/<topic name>/tutorials directory and update the material: entry of the metadata.yaml file as needed (see below section for further information).
  6. Place any referenced images into the topics/<topic name>/images/ directory.
  7. Commit and push these changes to your branch, and open a PR to the bich464 branch
  8. Once merged, they should be made viewable on the dev site.

New Tutorial in Existing Topic

  1. Create a new directory in the relveant topic directory at topics/<topic>/tutorials named <tutorial name>. This should be all lowercase and replace spaces with "-".
  2. Copy the contents of the templates/tutorials/tutorials1 directory into your new tutorial directory created in step 1.
  3. Modify the topic_name and tutorial_name information in the copied tutorial.md (found at topics/<topic name>/tutorials/<tutorial name>/tutorial.md).
    • topic_name should match the "name" entry in the relevant topic's metadata.yaml file
    • tutorial_name should match the lowercase/no spaces name used for the directory created in step 1
    ---
    layout: tutorial_hands_on
    topic_name: your_topic
    tutorial_name: your_tutorial_name
    ---
  4. Replace the template's markdown text with your own tutorial content.
  5. Update the topics/<topic name>/metadata.yaml file to properly show the tutorial information added into the topics/<topic name>/tutorials directory.
    • title, type, name, and contributors are all required.
    • One of hands_on, slides, galaxy_tour is required. We almost only ever create hands_on tutorial types.
    • The other blank entries can be used or removed as you will (zenodo_link, workflows, questions, objectives,time_estimation,key_points)
    • Names listed under contributors: should be github usernames that match an entry in the CONTRIBUTORS.yaml file in the repository root.
    • There should be one entry for each tutorial in the topic.
    • Indentation is important in yaml
    material:
      -
        title: "tutorial1"
        type: "tutorial"
        name: "tutorial1"
        zenodo_link: ""
        galaxy_tour: no
        hands_on: yes
        slides: no
        workflows: no
        questions:
          - ""
          - ""
        objectives:
          - ""
          - ""
          - ""
        time_estimation: "1d/3h/6h"
        key_points:
          - ""
          - ""
          - ""
          - "..."
        contributors:
          - contributor1
          - contributor2
  6. Place any referenced images into the topics/<topic name>/images/ directory.
  7. Commit and push these changes to your branch, and open a PR to the bich464 branch
  8. Once merged, they should be made viewable on the dev site.

Common Gotchas to Troubleshoot

  • Indentation
  • Matching tutorial.md tutorial_name field to metadata.yaml the materials: entry name field