Tools with sensible defaults for guiding the creation of new adventure workshops.
- Coloured syntax highlighting in exercise descriptions.
- Prints syntax highlighted solution on completion of an exercise.
- Add optional exercise boilerplate.
- Generates a user solution directory for each exercise.
- User solution directory includes exercise boilerplate & problem description.
Code generators for easily starting new workshops & exercises:
- Generate a new workshop with
adventure-map init. Creates minimal bootstrap (~20 LOC). - Generate a new exercise with
adventure-map new exercise-name: Bootstraps a few default files for an exercise (Readme.md,bootstrap.js,solution.js&verify.js)
I normally hate code generators so I've tried to make the code generation only spit out the most unopinionated code that you probably would have written anyway. All generated code is extremely simple and makes minimal assumptions. You can safely and easily modify the generated code to work however you wish.
TODO: custom code generation templates.
> adventure-map --help
Usage:
adventure-map init Bootstrap current directory.
adventure-map new [name] Bootstrap new exercise with [name].
You can use adventure-map to generate the minimal boilerplate for an
entire adventure. It includes a bootstrap file to load all the exercises
and an example exercise to use as a guide.
> mkdir test-adventure
> cd test-adventure
> npm init -f
> npm install --save adventure-map
> adventure-map init
exercises/example/Readme.md
exercises/example/boilerplate.js
exercises/example/index.js
exercises/example/solution.js
index.js
By default, exercises are loaded as "name": "relative/path/to/exercise" pairs
from your package.json. You need to add exercises to the package.json manually.
{
"name": "test-adventure",
"version": "1.0.0",
"main": "index.js",
"dependencies": {
"adventure-map": "1.0.0"
},
"exercises": {
"Getting Started": "exercises/example"
}
}If you don't like this convention of loading from the package.json, just change where the exercises load from, it's one line of code in the bootstrap code (see below).
After you've configured at least one exercise, can start your adventure:
> node index.js
The adventure bootstrap simply finds the exercises defined in your package.json and loads them into adventure.
#!/usr/bin/env node
var path = require('path')
var adventureMap = require('adventure-map')
var pkg = require('./package.json')
// resolve all package.json exercises relative
// to this directory.
Object.keys(pkg.exercises).forEach(function(name) {
pkg.exercises[name] = path.resolve(__dirname, pkg.exercises[name])
})
var adventure = adventureMap(pkg)
// auto-execute if run from commandline
if (!module.parent) adventure.execute(process.argv.slice(2))
// export for manual execution
module.exports = adventureThe boilerplate is just provided as a starting point, don't feel bad about changing any of the generated code.
You can use adventure-map to generate the required boilerplate for an
exercise:
> adventure-map new getting-started
exercises/getting-started/Readme.md
exercises/getting-started/boilerplate.js
exercises/getting-started/index.js
exercises/getting-started/solution.js
The exercise's script will load up the Readme, boilerplate and solution text for you, and provide a verify stub.
"use strict"
var fs = require('fs')
var path = require('path')
exports.problem = fs.readFileSync(__dirname + '/Readme.md', 'utf8')
exports.solution = fs.readFileSync(__dirname + '/solution.js', 'utf8')
exports.boilerplate = fs.readFileSync(__dirname + '/boilerplate.js', 'utf8')
var solution = require('./solution')
exports.verify = function(args, cb) {
var submission = require(path.resolve(process.cwd(), args[0]))
// insert validation logic
cb(false) // true if submission good
}
exports.run = function() {
// TODO
}You don't need to use the generated boilerplate in order to use adventure-map! Just pass it the adventure name and a mapping of exercise names and corresponding exercise paths.
You'll be passed back a substack/adventure instance.
var r = require('path').resolve
var adventureMap = require('adventure-map')
var adventure = adventureMap({
name: 'test-adventure',
exercises: {
'Getting Started': r(__dirname, 'exercises/getting-started'),
'Learning Things': r(__dirname, 'exercises/learning-things')
}
})
adventure.execute(process.argv.slice(2))adventure-map exercises follow the same format as adventure
exercises, with an additional boilerplate property:
module.exports = {
problem: 'problem text',
solution: 'solution code',
boilerplate: 'boilerplate code' // optional
verify: function(args, cb) {
// insert validation logic
cb(false) // true if submission good
},
run: function() {
// optional 'run' logic
}
}- Map logo designed by Ruben Verhasselt from the thenounproject.com.
- Big thanks to substack for the creation of adventure.
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent