Builder-CodeRoad

Create Interactive Tutorials

Builder-CodeRoad repo


Edit

1. What is Builder-CodeRoad?

Builder-CodeRoad is an Atom editor plugin for creating interactive Atom-CodeRoad tutorials.



Edit

2. Requirements

Atom-CodeRoad & Builder-CodeRoad both have several key dependencies before starting:

Name Min Version Description
NodeJS >0.10.x Check your version with > node -v
Download the latest from nodejs.org
NPM >3.x.x< Check your version with > npm -v
NPM comes installed with NodeJS,
and can be updated with > npm install -g npm
Atom Editor >1.6.0 A popular code editor available at Atom.io


Edit

3. Quick Start

To install builder-coderoad, you have two options:

  1. Inside of Atom, select the following menus:

    • Atom
      • Preferences
        • Install
          • search for “builder-coderoad”
  2. Use Atom Shell Commands.

> apm install builder-coderoad


Edit

4. Launch

Toggle open Builder-CodeRoad using the Packages menu or press ctrl-alt-9.



Edit

5. Configuration

Get setup quickly with CodeRoad: open the builder-coderoad plugin in an empty directory & click “start”.

Configuration Settings

Filling out the first page should create:

  • an example tutorial.md, which imports several tutorial files
  • an example test directory with a few example tests
  • a package.json configuration with some of the following settings:
{
  "name": "coderoad-$TUTORIAL-NAME$",
  "version": "0.1.0",
  "main": "coderoad.json",
  "keywords": [
    "coderoad",
    "tutorial"
  ],
  "coderoad": {
      "dir": "tutorial",
      "testSuffix": ".spec.js",
      "runner": "mocha-coderoad"
  }
}


Edit

6. Edit

Edit tutorial

The project view can be seen from the “edit” page.

Changes will update whenever you save a file from the text editor.

Clicking on items in the view will move your cursor to the corresponding code in the text editor.

From the “edit” page, you can also view your tasks. Tasks are composed of:

description

A summary of the task objective.

actions

Trigged changes in the users text editor, such as “open” a file or “insert” text. See the coderoad-API docs for more.

Hints

Helpful tips for the user.

Tests

Unit tests that verify task success and provide helpful failure messages. Learn more in the test docs. These are marked by the file path, in the side example: <> 01/01. Clicking on tests will route to the test page.

onPageComplete

A message that will display when all page tasks are complete. It is located in the blue box at the bottom.



Edit

7. Unit Tests

As previously mentioned, CodeRoad uses unit tests to verify task completion and provide feedback.

The “test” view allows you to run solutions against your tests to verify your tests are working.

This feature is currently not fully implemented. For now, you’ll have to check the console for test results.



Edit

8. Validate

Before publishing, be sure to validate your tutorial and package.json.

Validate view

Warnings may be ignored, but errors must be fixed before proceeding.



Edit

9. Publish

After validation, tutorials can be published to NPM.

Publish view

Select the type of version release:

Release Change Description
patch 0.1.0 -> 0.1.1 a fix
minor 0.1.0 -> 0.2.0 a new feature
major 0.1.0 -> 1.0.0 a breaking change

Publishing from “builder-coderoad” is not currently enabled. See the publish docs for how to do this from the command-line.



Edit

10. Roadmap