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.
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 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:
- Input Cells:
- Output Cells:
- Calculation Cells:
- Checkbox Cells:
- Tweet with Image:
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).
- 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 email@example.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 firstname.lastname@example.org; 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:
can be viewed via the URL:
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
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.
Needs more documentation.
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.
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.