smartdown - A Javascript library for translating, rendering, and interacting with Smartdown documents.
Smartdown is a declarative, literate and reactive authoring technology for writing technical and non-technical documents that are compelling and easy to share and publish within many existing forums and blogging systems. Smartdown is designed for blogging, technical communication, and teaching. Smartdown simplifies the creation of Explorable Explanations, which are prose documents with embedded interactive content such as charts, graphs, and featherweight programs called playables.
Smartdown extends the simple expressivity of the Markdown language commonly used on blogs, messaging systems, technical forums, and on GitHub. The Smartdown engine is a Javascript library that interprets the content in these Smartdown source files and enacts the desired behavior and presentation.
Markdown is an easy-to-learn set of conventions for annotating text for structure and formatting purposes. Markdown embraces the simple principle that the information in a document should be readable by default, and that any additional formatting syntax should be unobtrusive to this readability. Smartdown extends Markdown with additional media and content types for enhanced expressivity, and adds its own features including cells, playables, and reactivity.
I think that this principle is important when teaching students (of any age) how to present their ideas and eventually, to visualize their ideas. Unlike HTML and other syntax-restrictive media, Markdown enables an idea to be expressed in a crude form, and then iteratively refined into an ever-better expression of the idea. Sometimes that is simply a blog post with nicely formatted text and embedded graphics. Sometimes it might be an interactive webpage with P5JS graphics, an Explorable Explanation.
There are several variants of the original Markdown language; Smartdown adopts the GitHub-flavored Markdown variant as its base language. The basic elements of most Markdown implementations are described in this Markdown Cheatsheet.
Smartdown utilizes Markdown's link syntax and if it detects a Smartdown-formatted link, it replaces the link with a Smartdown cell, which can act as input, output, computation and more. A subset of the currently valid Smartdown cell types is below:
[Link Label](:@Location)[Input Label](:?VarName)[Output Label](:!VarName)[Calculation Label](:=Expression)[Checkbox Label](:XVarName)See Cells for detailed examples of Smartdown Cells.
Smartdown extends Markdown's idea of code blocks with the option of making such code playable. For example, the code for a Mermaid diagram can be displayed normally using a code block; however, by using Smartdown's /playable qualifier, the code can be executed and rendered within the document via the Smartdown-generated Play/Pause buttons:
```mermaid/playable
%% Example of sequence diagram
graph LR
id1((This is the text in the circle));
```
There is also an /autoplay option, which will ensure that the playable content is executed when the Smartdown card is loaded. These two options may be combined to produced autoplay content that may be manually played and paused. The use of /autoplay without a corresponding /playable will result in a playable that cannot be paused or its source displayed, which is often useful.
Smartdown is a flexible system for authoring and interacting with Explorable explanations, which are micro-apps composed of text, multimedia and code. Smartdown notebooks are written using an enhanced version of Markdown called Smartdown, which integrates MarkDown's ease-of-use with a reactive process engine.
Users of this technology include teachers, students, bloggers, and anyone who wants to easily create and publish their ideas, research, questions or explanations. The mission of Smartdown is to nurture idea inspiration, simplify the process of creation, and to encourage sharing and exploration of the resulting knowledge.
Smartdown is intended for teacher and student alike; the philosophy being that the best ways to learn a skill or concept are to use it and to teach it. A teacher might produce a Smartdown notebook for the purposes of teaching, and may then assign a student the task of explaining a learned concept by authoring their own notebook, which can then be shared (show and tell is a powerful technique).
This repository contains several tools and example web applications to illustrate Smartdown usage. The simplest one shows how to create a Smartdown-enabled site by including the Smartdown library and initializing it with content. The more complex one creates a web application that is able to dynamically accept and render Smartdown documents from a user, via drag-and-drop, file upload, or a URL parameter.
Visible at https://smartdown.site/lib, this simple Smartdown-enabled site renders a set of Smartdown files. Unlike the Smartdown Source Viewer Site below, this site does not support editing or the display of the Smartdown source files. It's basically an example of a static site of Smartdown content; in this case, the Smartdown Example Gallery.
The Simple Viewer Site does support the ability to view arbitrary Markdown or Smartdown files by appending the desired URL to the above URL, along with a hash (#) marker. For example, the following Markdown file:
https://cdn.rawgit.com/mozilla/mentat/ae91603b/README.md
can be viewed via the URL:
https://smartdown.site/lib/#https://cdn.rawgit.com/mozilla/mentat/ae91603b/README.md
The Smartdown Source Viewer application displays the same Gallery examples as above, but also supports a Show Source option which enables a user to view and edit the Smartdown source code, although these changes are not currently saved. Additonally, the Smartdown Source Viewer can be load and display local files selected via drag-and-drop, or by specifying the URL of a cloud-based Smartdown file as in the Simple Smartdown Viewer above.
For example, the URL above can be viewed via the Smartdown Source Viewer
https://smartdown.site/#https://cdn.rawgit.com/mozilla/mentat/ae91603b/README.md
See Gists for details on how Smartdown deals with Gists.
See Smartdown Via Gists for a very detailed tutorial on how to author Smartdown documents in GitHub Gists and then display.
Needs more documentation.
Use starter.js and index.html as guidance.
Needs more documentation.
Use starter.js and index.html as guidance.
For SublimeText users, we have a plugin that takes a directory of Smartdown files and colocated resources and then bundles them into an easily shareable and published .html file. See SmartdownPreview for details.
This software is still incomplete in its implementation, documentation, and attribution. I intend to add much better documentation as well as proper citation of the software I use. Right now, the only way to test it in the real world is to deploy it with a bunch of disclaimers like this one.
I will be making this project Open Source, but am still determining the proper license and getting all my release processes in place. Until then, the GitHub repository for smartdown will remain a Private repository and the software will be Copyright 2015, Daniel B Keith.
Principal Author: Daniel B Keith
email: feedback@infoclay.com
Twitter: @TheDoctorBud
GitHub: DoctorBud
Blog: https://doctorbud.com
