Grease - A Domain Specific Markup for Assessments

Recently I had a need to build a few assessments but I found a lot of the tools to be more complex than I wanted to work with. What I started doing was writing simple Markdown lists and then throwing them in Gist to have them parsed and useable. This left me with a bit of a problem in that I often forgot to write down what the correct answer was making marking slow. Thus, the Grease Language was born.


Let us start with an example to demonstrate how much this looks like Markdown.

# This is an assessment

1. What number month is September?
    * ( ) 10
    * (x) 9
    * ( ) 8

This can then be parsed into another format like HTML or JSON.

If you are familiar with Markdown, you may recognize these features:

  • lists
  • Github task lists
  • headings

That is because Grease is essentially a subset of Markdown.


Before going into the elements of Grease, lets make sure we're on the same page terms-wise. These are comment terms in the education field and they describe the parts of a question and answer(s).

  • Assessment: The general term for an exam, quiz, or test.
  • Stem: The portion that is most commonly called the 'question'.
  • Alternative: A potential answer.
  • Item: The grouping of single stem and a collection of alternatives.
  • Answer: The correct answer or answers to for this item.
  • Distractor: An alternative that is not the answer.


Tokens are language elements. You can think of them like tags in HTML. Grease has exactly six tokens in the first version.

# -- Assessment title
1. -- The stem
* [ ] -- A multiple select distractor (think checkbox)
* ( ) -- A single selection distractor (think radio button)
* [x] -- The multiple select answer
* (x) -- The single select answer


Since Grease is a "language", there is a tool I have created called Swivel. This is what you will use to parse Grease files.


There is currently no package for download, you need to compile it yourself 😭.

  1. Download the source code
  2. Open up your Terminal or Command Prompt and then change into the Swivel directory
    cd save_location/src/Swivel
  3. Run this build command using the dotnet cli
    dotnet build -c Release
  4. Locate your build! It will be located in an environment directory:
    # current directory: src/Swivel
    cd bin/Release/netcoreapp2.0/<your_environment>
  5. Copy the file to a folder in your PATH
    # on OSX/Linux
    cp Swivel /usr/bin/swivel
    # on Windows
    copy Swivel.exe "C:\Program Files (x86)\"