Create a Practice Tutorial

Create a CodeRoad tutorial

Follow these instructions carefully to create your first CodeRoad tutorial.

Create a repo

Go to GitHub and create a new repository for yourself named first-tutorial
After you click create, it takes you to the repo. Copy the URL for the repo, it should look like: https://github.com/your-username/first-tutorial.git
Open a terminal locally and find a place to clone your repo. Enter git clone https://github.com/your-username/first-tutorial.git with the repo URL you copied in place of that URL to clone it
Create a .gitignore file in your repo and add this to it:

node_modules
package-lock.json

Add anything else that may interfere such as .DS_Store if you are on a mac.

Create the markdown

Create a new file in your repo named TUTORIAL.md.

This is the file that describes the structure of a tutorial. It contains all the lessons, lesson titles, descriptions, test text and all the other verbiage that will be displayed to a user. Enter this markdown into the file and save it:

# Introduction

This is an introduction to your tutorial. It will show up on the first page when your tutorial is started.

## 1. Create index.html

> Optional summary for Level 1

Here's where you can put a description, examples, and instructions for the lesson.

### 1.1 Level 1 Step 1

This is the test text. Create an `index.html` file to pass this lesson.

#### HINTS

- This is a hint to help people through the test
- Second hint for 1.1, don't worry if the hints don't show up yet

The above tutorial has an introduction page and one lesson.

Commit to GitHub

Back in the terminal, add all your new files to be committed with git add .
Commit them with git commit -m "create markdown"
Push them to GitHub with git push origin master

Create a version branch

Create and checkout a new orphan branch with git checkout --orphan v0.1.0.

This will make a branch that isn't created from master, so it has no commit history. It will hold the tests for your tutorial. Each test is its own commit. You can also add an optional commit for a solution to each test.

Check your git status
Delete the tutorial file from this branch with git rm -f TUTORIAL.md

Create your project files

This branch is also where users create their projects, modify files for a tutorial, and anything else that they need to do.

Make a new folder named coderoad on your branch.

This folder will hold as much of the CodeRoad stuff as it can so users aren't confused with extra files in their projects.

Go to the coderoad folder in your terminal and run npm init. Press enter until you are through the setup.
Open the package.json file you just made and make it look like this...

{
  "name": "coderoad",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "programmatic-test": "mocha --reporter=mocha-tap-reporter",
    "test": "mocha"
  },
  "author": "",
  "license": "ISC"
}

These scripts will be for CodeRoad and for you to test things.

From the terminal, in your coderoad folder, run npm install --save mocha mocha-tap-reporter to install some depenedencies
Go back to the main repo folder and add your changes with git add .
Commit your files with git commit -m "INIT"

The message of INIT in all caps is necessary. This message is used to add project setup files and anthing else you want to add before a user starts the tutorial.

Push and Create a branch on your remote with git push -u origin v0.1.0

Create the first test

Go in the coderoad folder and create new folder named test in it
Create a file named first-tutorial.test.js in the test folder
Add this to the file:

const assert = require('assert')
const fs = require('fs')
const util = require('util')
const path = require('path')

const readdir = util.promisify(fs.readdir)
const getRootDir = async (dir = process.cwd()) => {
  const pathToRoot = path.join(dir, '..')
  const rootDir = await readdir(pathToRoot)

  if (!rootDir) {
    throw new Error(`Could not find folder ${pathToRoot}`)
  }

  return rootDir

#Create a CodeRoad tutorial

#Create a repo

#Create the markdown

#Commit to GitHub

#Create a version branch

#Create your project files