General Information

The presence of the techio.yml file is mandatory at the root of the git repository of a playground.

This file contains the plan of the playground, the references to the playground files, and the technical details to correctly build a playground associated to the repository.

Main section

The main section of techio.yml contains the title and a plan of your playground. The content and the hierarchical structure of a playground is defined by the plan. The information required to correctly build and run the technical part of a playground is defined by the projects element.

# The playground title.
# type: String
title: playground title

# Specify a cover for your playground.
# This is a small image (jpg/png) that will be displayed
# in the playground card. By default, you can also create
# a cover.jpg (or cover.png) at the root of your repository
cover: /path/to/an/image.jpg

# The root of the playground plan. The plan can either be composed of chapters
# or lessons.
# type: Ordered List of Chapter or Lesson
plan: See Chapter or Lesson

# The root element of the projects list.
# type: Ordered Map of Project
projects: See Projects section

Lesson

A Lesson is displayed as a single page on Tech.io.

# The root element of a Lesson.
# type: Ordered List
plan:
      # The lesson title.
      # type: String
    - title: The lesson title
      # The statement content file. The path is relative to the git root
      # directory.
      # type: String
      statement: /path/to/lesson1.md

Chapter

In our terminology, a chapter is an ordered list of Lessons. Thus, it is the hierarchical level above the concept of lessons. This hierarchical level is optional since playgrounds can only consist of lessons.

A chapter has a title, a description, and contains a list of lesson (plan). The description consists of a few lines of text which describe the purpose of the chapter and are displayed in the table of content.

# The root element of a Chapter.
# type: Ordered List
plan:
      # The chapter title.
      # type: String - default value: Unnamed
    - title: The chapter title
      # Few lines of text which describe the purpose of the chapter.
      # type: String
      description: This fields contains the description of the chapter.
      # The root of the lessons plan of this chapter.
      # type: Ordered Map of Lesson
      plan: See Lesson

Projects

The projects element contains a list of projects. A project contains the technical elements necessary to build and run interactive code section of a lesson.

# The root element of the projects list.
# type: Unordered Map
projects:
    # The project id. The project id will be referenced by tests.
    # type: Unordered Map
    my-playground:
        # The root directory of the project. This root path is relative to the
        # git root directory. The content of this directory will be copied
        # into the builder source path (see Builder section for more details).
        # type: String
        # default value: /
        root: /path/to/root/sources

        # The build command can reference a script from your git project, or
        # a set of commands (e.g: cd /project/target && npm install) that will
        # be executed in the runner image, at build time.
        # It allows you to use standard docker images and perform “install”
        # or “setup” actions in the new images, for instance
        # fetching dependencies.
        # It *replaces* the build script that may already exists in your
        # personalized docker image. Note: you can still call the standard
        # /project/build script of the image from your own script.
        # (see Runer reference documentation for more details on build scripts).
        # type: String
        buildCommand: cd /project/target && ./my-install-script.sh

        # The runner image reference. See runner element details for more
        # information.
        # type: Ordered Map representing a Runner
        runner: See Runner

Runner

The runner enters in action when a user click on the RUN button inside an interactive programming section in a lesson.

All the technical specification about the creation and the use of a Runner can be found in the Runner Reference Documentation.

# The runner root element.
# type: String
runner: junit-runner:1.0.0

This additional syntax is also valid:

# The runner root element.
# type: Unordered Map
runner:
    # The runner docker image name. It will be downloaded from the docker hub.
    # type: String
    name: junit-runner
    # The docker tag to use for the image
    # type: String
    version: 1.0.0

Example

title: My playground title
cover: /playgrounds/cover.png
plan:
- title: My first chapter title
  description: This is a quick description of my first chapter.
  plan:
  - title: Lesson 1 of Chapter 1
    statement: /playgrounds/chapter1/lesson1.md
  - title: Lesson 2 of Chapter 1
    statement: /playgrounds/chapter1/lesson2.md
- title: My Second chapter title
  description: This is a quick description of my second chapter.
  plan:
  - title: Lesson 1 of Chapter 2
    statement: /playgrounds/chapter2/lesson1.md

projects:
    my-java-playground-project:
        root: /project
        buildCommand: ./install.sh
        runner: junit-runner: 1.0.0