active-markdown

Active Markdown, v0.3.0

2013-4-28

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 content 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: am_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-0.3.0-min.css
  http://activemarkdown.org/viewer/activemarkdown-0.3.0-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.

• -c --collapsed_code Collapse the code blocks by default.

• --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.

• --debug Set the debug flag when compiling, using unminified versions of the viewer asset files and providing error feedback.

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 docs/reference.html for a complete reference of the elements and their configuration.

API

The ActiveMarkdown module allows for programmatic parsing of Active Markdown, in Node via require 'active-markdown', or in the browser by including the script asset file.

See docs/api.html for details.

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.3.0

Major refactor and modularization, allowing for use in-browser. Also exposes an API for programmatic parsing. Most viewer libraries are included as npm packages, then bundled using browserify. Also, charts!

Bugfixes

• RangeElement text content parsing
• Parsing of intervals with constants

Features

• ActiveMarkdown module for server-side and in-browser usage
• Charts, using Vega/d3, with an image-like notation
• command: --collapsed_code for setting active code blocks as collapsed by default
• command: --debug option, with unminified libraries and error feedback
• viewer: In-page controls
  • Collapsable active code blocks
  • Highlight active elements
  • View/download raw version
• viewer: Style improvements, particularly active code blocks
• dev: Improved build process, with --firstrun flag and a task for releases
• docs: API reference