Open Source Your Knowledge, Become a Contributor
Technology knowledge has to be shared and made accessible for free. Join the movement.
Goal & Prerequisites
The goal of this tutorial is to demonstrate how to build a basic playground on the platform.
You only need:
- Git installed on your computer.
- Basic knowledge about Git (clone, push)
The source code of this documentation is on GitHub (Documentation GitHub repository, please feel free to come up with proposals to improve it.
Create a playground
Go to the Create a playground page. Here, you can choose a template from a large selection of technologies. A skeleton playground based on the selected template is created in a new git repository.
Templates contain a working code example and some hints to help getting started.
You can also choose to create an empty playground.
Get your playground
To modify this playground, you need to be authenticated on Tech.io’s Git Platform. To do so, you need to add a SSH key to your profile.
If you don’t already have an SSH key, execute
ssh-keygen in your terminal. This command creates a public and a private key used to access your repository. (Check out GitHub Help for more information).
By default, the public key is located in
~/.ssh/id_rsa.pub. Copy your public key to your settings page.
Now that your key has been added, you can clone your repository using the origin URL provided on the playground page:
git clone firstname.lastname@example.org:cg123456/playground-hash.git
Structure of a playground
Now that you have cloned the project, let's take a look at the folder structure:
techio.yml: This mandatory file must be present at the root of a playground’s git repository and contains: table of content of the playground, the references to the lesson files, and some other technical details for advanced usage (discuessed later in the documentation).
cover.png: This small image is displayed when your playground is displayed on the platform. Feel free to change it.
markdownsfolder: This folder contains lesson statements.
projectfolder: We'll describe this later in the [Add a coding exercise](/getting started/tutorial-3-coding-exercise.md) section of the documentation.
techio.yml contains the following details:
- title : The title of your playground which appears on the playground page.
- plan: The plan of your playground is described as list of the lessons. Each lesson is composed of a title (which appears in the table of contents) and a statement as a link to a markdown file, relative to your root folder.
/!\ Do not use tab characters in this file, only spaces are allowed.
Have a look at the reference for all available options: techio.yml reference.
Statement & Markdown
Lesson statements are markdown files. Markdown is a simple syntax for basic formatting (links, images, quote text, code formatted text snippets, etc).
You can find a cheatsheet for markdown here.
The repository skeleton contains a folder with one lesson, under the
Update your playground
First, change the content of
# Hello world, welcome to my course. This is the first lesson.
Then, change the
techio.ymlto update the title of your playground:
title: Put your playground title here plan: - title: Welcome statement: markdowns/welcome.md
Deploy on tech.io
Now that you've changed your playground, you need to deploy it on Tech.io. Commit your changes and push them to Tech.io using the following git commands:
git commit -a -m "My first changes" git push origin master
Play with your playground
Come back to your playground page on Tech.io. It should have refreshed. Click "Preview" to play with your playground.
Add a new lesson
If you want to add a new lesson, follow these steps:
- Create a markdown file:
- Edit this markdown and add content
- Reference this markdown in
title: Put your playground title here plan: - title: Part 1 statement: markdowns/welcome.md - title: Part 2 statement: markdowns/part2.md
- Push your changes
git commit -a -m "Add Part 2" git push origin master
- Navigate back to your playground on Tech.io. Once it has refreshed and finished building, you can preview your modified playground.
Share your playground
Once you're satisfied with your playground, it's time to share it with the world. You can make your plaground go 'live' by clicking the "Publish" button. It will shorten the url and publish it on your Tech.io profile. You can also share the link to your friends.
Future updates to your plaground
When a playground is published and consumed by learners, you can freely update it with improvements and use the preview to see the results impacting users. Once you're satisfied, publish it again and the users will see the changes.