# Git Repository Structure

The most common case is to have one separated repository containing the katacoda scenarios. The scenarios should be placed into directories in the root of the repo git.

scenario-examples.git
├── README.md
├── assets
│   ├── avatar.png
│   └── test.css
├── clipboard
│   ├── index.json
│   └── step1.md
├── create-course
│   ├── finish.md
│   ├── index.json
│   ├── intro.md
│   ├── step1.md
│   ├── step2.md
│   ├── step3.md
│   └── step4.md
├── create-scenario-101
│   ├── finish.md
│   ├── index.json
│   ├── intro.md
│   ├── step1.md
│   ├── step2.md
│   ├── step3.md
│   ├── step4.md
│   └── step5.md

In this example the directories clipboard create-course and create-scenario-101 are scenarios of katacoda scenarios example git repo.

If you are using a repo git that is not dedicated to katacoda scenarios, you can define the directory where your scenarios are located using a katacoda.yaml file in the root of your repo git with the scenario_root property.

no-dedicated-repo.git
├── README.md
├── katacoda.yaml
├── app-directory-1
├── app-directory-1
├── tutorials
│   └── katacoda
│       └── clipboard
│           ├── index.json
│           └── step1.md

Considering the git structure, the content of katacoda.yaml should be:

scenario_root : tutorials/katacoda

# Scenarios

A katacoda scenario is a series of markdown files, bash scripts and a JSON file to define how your scenario should be configured, the text for the scenario and any automation required.

# Internationalization

To have the scenarios for different languages, you need to create a directory with underscore, and the prefix of the language at the root of your repo, containing the markdown files according with the language. The name of the directories should be the same for all the languages, for example, considering your scenarios are create-course and create-scenario-101 the scenarios for Spanish are located under the _es with the same name create-course and create-scenario-101:

scenario-examples.git
├── create-course
│   ├── assets
│   │   └── launch.sh
│   ├── env-init.sh
│   ├── finish.md
│   ├── index.json
│   ├── intro.md
├── create-scenario-101
│   ├── assets
│   │   └── launch.sh
│   ├── env-init.sh
│   ├── finish.md
│   ├── foreground.sh
│   ├── index.json
│   ├── intro.md
│   ├── step1.md
│   ├── step2.md
│   ├── step3.md
│   └── step4.md
├── README.md
├── _es
│   ├── create-course
│   │   ├── assets
│   │   │   └── launch.sh
│   │   ├── env-init.sh
│   │   ├── finish.md
│   │   ├── index.json
│   │   ├── intro.md
│   ├── create-scenario-101
│   │   ├── assets
│   │   │   └── launch.sh
│   │   ├── env-init.sh
│   │   ├── finish.md
│   │   ├── foreground.sh
│   │   ├── index.json
│   │   ├── intro.md
│   │   ├── step1.md
│   │   ├── step2.md
│   │   ├── step3.md
│   │   └── step4.md

Practice the creation of your first scenario with Create scenario 101

# Courses

The scenarios can be grouped by a common subject, and this is represented with a course. A katacoda course is defined by creating a pathway file. The pathway defines which scenarios should be included in the course and the order to display them.

The pathway file should be named with the same name of the directory, followed by the suffix -pathway.json. For example, in the katacoda scenarios example repo git we have a course with all the layouts available, the course is uilayouts we have the scenarios uilayout-editor-terminal, uilayout-iframe, uilayout-terminal, etc. The pathway file to define this course is uilayouts-pathway.json

scenario-examples.git
├── uilayouts
│   ├── uilayout-editor-terminal
│   │   ├── index.json
│   │   ├── intro.md
│   │   ├── setup.sh
│   │   └── step1.md
│   ├── uilayout-iframe
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-iframe
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-iframe-split
│   │   ├── index.json
│   │   └── step1.md
│   ├── uilayout-terminal-terminal
│   │   ├── index.json
│   │   └── step1.md
│   └── uilayout-terminal-with-vscode
│       ├── index.json
│       └── step1.md
├── uilayouts-pathway.json

The content of uilayouts-pathway.json:

{
  "title": "Katacoda UI Layouts Example",
  "description": "Example of different Katacoda UI Layouts. Also, an example of creating a Katacoda Course!",
  "icon": "fa-katacoda",
  "courses": 
  [
    {
      "course_id": "uilayout-terminal",
      "title": "Scenario with Terminal UI",
      "description": "Katacoda Scenario Example"
    },
    {
      "title": "Scenario with Terminal and VS Code UI",
      "pathway_id": "scenario-examples",
      "course_id": "uilayout-terminal-with-vscode"
    },
    {
      "course_id": "uilayout-editor-terminal",
      "title": "Scenario with Editor Terminal UI",
      "description": "Katacoda Scenario Example"
    }
    ...
  ]
}

Check this example scenario about courses.

# Pathway Parameters

Element Description
title Title of the course to use on Katacoda.com
description Description of the course to ues on Katacoda.com
icon Icon to use when showing the course on Katacoda.com
private Set to true if you want to make the scenario only accessible via the Embed API or to other members of your organization within Katacoda. Additional controls are available with a paid subscription

# Courses Parameters

Element Description
course_id The folder name of the scenario
title Title of the scenario to show on the course page. This can be different from the scenario title
description Description of the scenario to show on the course page

# Training

If you are planning to run workshops where you need to ensure the capacity for the expected number of attendees, you will need to create a pathway file, describing the scenarios you want to include in it. This pathway file should be located in the training directory of your git repo.

The training pathway defines the scenarios that will be delivered via instrutor-led workshop. This allows you to combine different scenarios to create a unique course that be re-use the same pathway across multiple events.

The file should be committed to the Git repository within a directory called training with -pathway.json as the suffix.

For example, this is istio-pathway.json.

{
  "title": "Istio and Kubernetes Workshop",
  "description": "",
  "courses": [
    {
      "pathway_id": "istio",
      "id": "workshop/deploying-istio",
      "course_id": "deploying-istio",
      "title": "Deploying Istio to Kubernetes",
      "description": "Learn how to deploy Istio to a Kubernetes cluster"
    },
    {
      "pathway_id": "istio",
      "id": "connecting-controlling-microservices/traffic-shaping",
      "course_id": "traffic-shaping",
      "title": "Connecting & Controlling: Traffic Shaping Microservices Connections",
      "description": "Learn Load Balancing, Routes, Rules with Istio"
    }
  ]
}

# Pathway Parameters

Element Description
title Title of the course to use on Katacoda.com
description Description of the course to ues on Katacoda.com
courses Collection of scenarios that will make up the course
private Set to true if you want to make the scenario only accessible via the Embed API or to other members of your organization within Katacoda. Additional controls are available with a paid subscription

# Courses Parameters

Element Description
pathway_id Name of the scenario owner account. This is likely to be your username
course_id The ID of the scenario, created based on the directory name. If scenario is in a sub-course then include the directory name.
id The ID of the scenario. If the scenario is in a sub-course, the directory name should not be included
title Title of the scenario to show on the course page. This can be different from the scenario title
description Description of the scenario to show on the course page

Live example of the created course page can be viewed at https://www.katacoda.com/ben_hall/training/istio

# Moving Katacoda Content To Sub-Directory

By Default the Katacoda content is located at the top-level of a Git repository.

In the root of the repository, create a file called katacoda.yaml. The contents of the YAML content should have the element scenario_root which points to the directory in the repository that has the Katacoda content. For example:

scenario_root: subdirectory/storing/katacoda/content

The structure of the content within this directory should then be the same as above.

A live example of this is how https://github.com/thanos-io/thanos is structured with https://github.com/thanos-io/thanos/tree/master/tutorials/katacoda storing the Katacoda tutorials.