# 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 an underscore, and the prefix of the language at the root of your repo, containing the markdown files according to 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"
},
{
"course_id": "uilayout-editor-terminal",
"title": "Scenario with Editor Terminal UI",
"description": "Katacoda Scenario Example"
},
{
"course_id": "uilayout-terminal-with-vscode",
"title": "Scenario with Terminal and VS Code 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 use 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. |
# 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 |
# 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 that 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.