Widgets

The official Kumu markdown widget collection.

We've extended the marked markdown library to support custom widgets through a simple [[widget]] syntax. Widgets are ridiculously easy to write and we'd love to accept pull requests for new ones! (See the contributing guide at the bottom.)

Basics

Widgets are handled through a simple uri-based router. Required parameters are handled through named parameters, with optional parameters handled through the query string.

[[vimeo/86389108?aspect=hd]]

Defining Widgets

All you need is a function to render the widget and a route to attach it to.

Here's the full vimeo widget as an example:

// lib/widgets/vimeo/vimeo.jsfunctionrender(id,options){returnthis.template("vimeo/vimeo",{src: "//player.vimeo.com/video/"+id+"?title=0&byline=0&portrait=0",aspect: options.aspect});}module.exports=function(widgets){widgets.add("vimeo/:id",render,{aspect: "hd"});};

<!-- lib/widgets/vimeo/vimeo.jst --><divclass="widget-container" data-aspect-ratio="<%- aspect %>"><divclass="widget-content"><iframesrc="<%- src %>" frameborder="0" width="100%" height="100%"
webkitallowfullscreenmozallowfullscreenallowfullscreen></iframe></div></div>

(Note: Templates are rendered using underscore templates.)

Contributing

We'd love for you to add your own custom widgets. It's easy to get started.

// Step 1. Make sure node / npm installed
node --version
npm --version
// Step 2. Install mocha globally (for testing, may require sudo)
npm install -g mocha

Basic process for adding new widgets:

• Fork the project
• Create a feature branch git checkout -b add-mywidget
• Install dependencies make install
• Add your widget (see test/widgets/vimeo for example)
• Add some tests
• Submit a pull request

Please limit each pull request to a single widget.

Testing

Run make test to run the test suite.