Display and interact with Smartdown documents
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
CONTRIBUTING.md
LICENSE
README.md

README.md

smartdown

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.

Other Smartdown examples via Glitch

Markdown and Smartdown

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 Cells

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:

  • Tunnels: [Link Label](:@Location)
  • Input Cells: [Input Label](:?VarName)
  • Output Cells: [Output Label](:!VarName)
  • Calculation Cells: [Calculation Label](:=Expression)
  • Checkbox Cells: [Checkbox Label](:XVarName)
  • Tweet: ![](https://twitter.com/nasa/status/735978603431768065)
  • Tweet with Image: ![](.../status/735978603431768065&showMedia)

See Cells for detailed examples of Smartdown Cells.

Smartdown Playables

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.

Philosophy

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

FAQ

  • Is this Beta Software? Yes. It is useful and usable, but it lacks many of the finishing touches necessary for it to be complete.
  • Is this open source? No, not yet. It is currently Copyright Dan Keith, 2015. I'm currently working on establishing a core team of developers and the necessary license agreements to assure sustainability of the project. Please contact feedback@infoclay.com if you'd like to help, have advice, or want to cheer me on.
  • How are you going to make a living off of this? I have no idea! Smartdown is something I want to exist. I'm hoping that someone else finds it useful and that maybe there will be a way for me to keep working on it. Right now, it's a weekend and spare time project unassociated with my day job.
  • How can I provide feedback? - Send an email to feedback@infoclay.com; any feedback is appreciated. I am working on creating a more flexible and interactive means of user feedback.
  • What is InfoClay? InfoClay is the name of an interactive authoring environment wherein Smartdown was initially conceived, and then isolated as a separate library. InfoClay is still under development as KnowBench, but my priorities have been on stabilizing and releasing Smartdown. But in much of the documentation and examples, InfoClay and Smartdown mean the same thing: markdown-based, interactive, reactive explorable explanations.

Ways to Share and Publish Smartdown

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.

Simple Viewer Site

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

Smartdown Source Viewer Application

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

Using GitHub Gists to store Smartdown files

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.

Via a Blog

Needs more documentation.

Use starter.js and index.html as guidance.

Via Wordpress

Needs more documentation.

Use starter.js and index.html as guidance.

Via SmartdownPreview

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.

Contributing

Pre-Release Warning

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.

Licensing and Open Source

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.

Contact Info

Principal Author: Daniel B Keith email: feedback@infoclay.com Twitter: @TheDoctorBud GitHub: DoctorBud Blog: https://doctorbud.com