active-markdown

Active Markdown, v0.2.0

Active Markdown is a tool for making reactive documents — in the vein of Tangle — using a plain text markdown source, with a special notation for adding interactive controls and variables. The logic is determined by the contents of the code blocks, which is actually executed on-the-fly to update the variables.

A sample raw Active Markdown file looks like this:

# St Ives

An old riddle.

> As [I]{travelers: we or I} [was]{verb} going to *St Ives*  
> I met a man with [7 wives]{wives: 1..10}  
> Every wife had [7 sacks]{sacks: 1..10}  
> Every sack had [7 cats]{cats: 1..10}  
> Every cat had [7 kits]{kits: 1..10}  
> Kits, cats, sacks, wives  
> How many were going to St Ives?

    total_sacks = @wives * @sacks
    total_cats  = total_sacks * @cats
    total_kits  = total_cats * @kits
    man         = 1

    if @travelers
        narrator = 2
        @verb = 'were'
    else
        narrator = 1
        @verb = 'was'

The first guess is often [2753]{first_guess}…

    @first_guess = man + @wives + total_cats + total_kits + narrator

…but the correct answer is **[1]{answer}**.

    @answer = narrator

(rendered form »)

…where the [7]{wives: 1..10} gets replaced with a slider from 1 to 10, defaulting at 7. Whenever the value of one of the variables is changed, the code in the given code block is executed using the current state of all the variables. Then, the variables are updated with the new state.

The notation is similar to the syntax for images and links, but when combined with some UI code by the rendering command, creates a rich, interactive and reactive document. Inspired by literate CoffeeScript and Tangle, the goal is a lightweight format for specifying interaction without requiring the creation of a webapp. Also, the document exposes its logic directly, and allows for easy modification and experimentation.

[text value]{var_name}                  - interpolated variable (readonly)
[5]{var_name: 1..10}                    - slider from 1 to 10, default 5
[this]{var_name: this or that}          - toggle switch between `this` or `that`

The code blocks have access to these variables under the top-level this object. Also, the code blocks are editable, and recompiled for every execution, allowing for additional interactivity. (Note: the code in the code blocks MUST be CoffeeScript.)

This is still experimental, and very rough around the edges. For more information, see the initial writeup.

Active Markdown uses Showdown for markdown–HTML conversion, with the github and table extensions enabled.

0–60 (getting started)

1. Install:

   $ npm install -g active-markdown
   

2. Compile an Active Markdown-formatted file:

   $ activemd file.md
   Compiled file.md -> file.html
   

   The command can generate a sample file for you to use and examine.

   $ activemd --sample
   Generating sample: sample.md
   
   $ activemd --sample > some_name.md
   Generating sample
   

3. Open the compiled file in your favorite browser:

   $ open file.html
   

Usage

The basic usage is activemd FILE. This will compile a markdown file with the Active Markdown notation into an HTML file

activemd [options] FILE(S)

Options:

• -l --local Create local copies of the asset files, relative to the specified source file(s). By default, the assets used are remote, specifically:

  http://activemarkdown.org/viewer/activemarkdown-X.Y.Z-min.css
  http://activemarkdown.org/viewer/activemarkdown-X.Y.Z-min.js
  

• -i --inline Inline the asset files in the template. Similar to --local, but includes the content of the assets in the actual output file, creating a single, self-contained Active Markdown viewer file.

• --title TITLE Use the specified string as the title of the compiled HTML file.

• --sample Generate a sample file that contains all of the possible controls in various configurations.

Notation

The notation for specifying elements is similar to the regular Markdown syntax for links and images, generally following this format:

[text content]{variable_name: configuration}

See activemarkdown.org/reference.html for a complete reference of the elements and their configuration.

Authors

• Alec Perkins (Droptype Inc)

Thanks to J Voight, Alex Cabrera, John Debs, and Supriyo Sinha for help with the notation.

The concept and controls are heavily influenced by Bret Victor’s Tangle library for creating reactive documents.

• You? - Active Markdown is still very experimental, and input on the notation, bugs, use cases, control elements, and anything else is very welcome.

License

Unless otherwise noted, this software is Unlicensed, aka Public Domain. See /UNLICENSE for more information.

Changelog

0.2.0

Tests and cleanup, with a better build process via $ cake.

Bugfixes

• Parsing decimal numbers with constants
• Parsing negative numbers
• Code block cursor visibility
• Invoking command with no arguments
• Outputting to file when input is piped
• Referenced viewer library pinning

Features

• Tests! (using Mocha)
• --title option for specifying output document title
• Notation reference
• Ignoring of language-specific code blocks
• Improved viewer styles
• Linking to section headings