Smartdown via bl.ocks.org

.block

license: none
height: 700
scrolling: yes
border: no

README.md

Smartdown via Gists and bl.ocks.org

Smartdown is currently in a beta-testing phase, and the source code is not yet publicly available, although the plan is to make it open source once it stabilizes more.

This tutorial is best experienced in raw mode. Please continue at README

This tutorial describes how to author a simple Smartdown example, extend it, and then make it available for show-and-tell via bl.ocks.org and via the Smartdown Viewer. Thanks for your patience and help in building a better Smartdown experience.

Smartdown is an accessible, yet powerful, way to author and explore ideas, be they technical, philosophical, or artistic. By design, it is an open format building upon other open standards and open source technology. Smartdown notebooks may be published via a variety of existing platforms and tools, including WordPress and GitHub Pages.

Recently, I've begun to use bl.ocks.org as a platform for sharing and publishing Smartdown notebooks and fragments. About Blocks describes the site as:

Bl.ocks (pronounced "Blocks") is a simple viewer for sharing code examples hosted on GitHub Gist.

but in my opinion it is a very powerful tool and the author, Mike Bostock has done a wonderful job in making it practical and fun.

The best way to experience Smartdown and this tutorial is via the Block link, which focuses on the Smartdown content and hides the details of the component files.

Authoring.md

Enhancing your Notebook

You will add more interesting Smartdown content to your notebook.

Congratulations! You've created a Gist and arranged it so that it renders the Smartdown content in the Home.md file as a Block via bl.ocks.org. Now it's time for you to get a little more comfortable with the Gist/Block relationship, and with Smartdown itself. So this part of the tutorial will show you how to extend your notebook with additional linked cards, and how to customize your Block's display to be taller and scrollable.

Add and Link to Additional Smartdown Cards

By default, Home.md is the card used for the notebook's landing card. You may add other files to your Gist, and then write a Smartdown link to that card; e.g., [My New Card](:@MyNewCard) will load the content of MyNewCard.md from the Gist and replace the currently loaded card.

To try this out, and to prepare for some of the other experiments below, create a new File in your Gist called, Playground.md (using the same Add File ... Update Gist trick you learned previously). Paste the following text into the Playground.md file and then save your Gist. Don't worry too much about the details for now, just make sure you copy all of the Smartdown text below starting with ## Welcome to the Playground and ending with [Back to Home](:@Home).

## Welcome to the Playground

This card demonstrates the synergy between Smartdown cells and playables. In this case, we are using a [P5JS](https://p5js.org) playable to draw a *sketch* and react to changes in the `Name` variable via the `What is your name?` input field.

---

[What is your name?](:?Name)

Click the triangular `Play` button to play this Sketch, [](:!Name).

```p5js/playable
p5.setup = function () {
  p5.resizeCanvas(p5.windowWidth / 2, 150);
};

p5.draw = function() {
  p5.background('darkgray');
  var name = env.Name || 'Someone';
  p5.fill('lavender');
  p5.ellipse(50, 70, 80, 120);
  p5.textSize(32);
  p5.fill('lightgreen');
  p5.text(name, 100, 40);
  p5.fill('lightblue');
  p5.text(name, 100, 70);
  p5.fill('pink');
  p5.text(name, 100, 100);
};
```

---

[Back to Home](:@Home)

Once you've saved your Gist with Playground.md, you will want to link to it from Home.md. So edit Home.md and add the following list item to the top of the list that begins with - More info at:

- [Visit the Playground](:@Playground)

So your new Home.md should begin something like:

# Smartdown is Markdown, and More

- [Visit the Playground](:@Playground)
- More info at [Smartdown Viewer Site](https://smartdown.site)
- Styles: **bold** or *italic* or ~~strikethru~~

At this point, if you wait a few seconds to minutes, you should be able to refresh the page showing your Block and see the updated Home card, with a link button. Clicking the Visit the Playground button should take you to the Playground, where you can use Back to Home to get back to the Home card.

Customize your Block with .block

You may have noticed that when you view your Block, the Smartdown content does not fully display and is clipped at the bottom of the Tweet example. This problem goes away when you use the Open link on the lower right corner of the displayed Smartdown content, but in many cases you many want a reader of your content to view the entire Block, which includes source code. Fortunately, the author of bl.ocks.org anticipated this and you can control the height and scrollability of your content by adding a special file in your Gist called .block. The full details are at About bl.ocks.org.

You've already learned how to add files to your Gist, so next you will add a new file named .block with the following contents:

height: 700
scrolling: yes

Save your Gist with this new .block file and your Block will display as 700 px units high instead of the default 500 px. In addition, it will now have a scrollbar to let you reveal the formerly hidden content.

---

Step 3: Add Smartdown Essentials Step 5: Review and Share

Back to Home

FAQ.md

Frequently Asked Questions

Delay between GitHub and bl.ocks.org

When you make changes to your Gist, it may take anywhere from a couple seconds to several minutes before these changes are reflected and visible on bl.ocks.org. Don't Panic, it will work itself out.

Bookmarks, hashes, and forward/back buttons

Blocks are initially displayed in the default iframe mode, which presents the block content within an HTML <iframe> container, followed by the block's README and the sources for the block's component files. In this mode, Smartdown is able to see the Browser's URL, but cannot affect it. So I can add #Authoring to the end of my block's URL and share the result with a friend, so that when they view the block, they will see the Authoring card, rather than the default Home card. For example, the link:

• https://bl.ocks.org/DoctorBud/f3895d12abbe282bcd9a440ff12a0d47/#Authoring

should take you to the Authoring Card for this current block.

However, in iframe mode, the browser's forward/back buttons will not apply to any internal navigation within the Smartdown content, as that relies upon the current card being recorded in the URL via the hash suffix at the end of the URL.

In raw mode, available via the Open link to the right of the README, the Block content (Smartdown, in this case) has its own browser window without any of the README or source files displayed. In Raw mode, Smartdown can both view and modify the browser's URL, so that bookmarking, forward/back, and other full-browser features are available.

In addition to the Open link on the iframe block page, the raw URL can also be constructed by inserting /raw into the block's URL. For example:

• https://bl.ocks.org/DoctorBud/raw/f3895d12abbe282bcd9a440ff12a0d47/#Authoring

Smartdown seems to use a lot of memory/bandwidth

Because Smartdown currently bundles a variety of powerful open-source software to manifest its features, the initial download of your first Smartdown notebook will take more time than a simple web page. However, once cached in your browser, you should not notice any additional overhead. Smartdown is a serverless system that runs entirely in a modern web browser.

When playing Smartdown playables such as P5JS, D3, or Javascript, it is possible that additional CPU or network overhead may be incurred, but that's usually because the playable is doing something useful, like contacting Wikidata or rendering a compelling visualization.

Other ways to use Smartdown

If you don't have a GitHub account and don't want one, then you will still be able to explore published Smartdown Notebooks, as well as using the other Smartdown publishing and viewing applications, including:

• Smartdown Viewer provides many Smartdown examples, as well as a means of viewing local and cloud-based Smartdown files.
• SublimeText users can edit their Smartdown files and instantly generate an HTML file to preview their content. See the smartdown/sublime-text-tools.
• The Smartdown NPM Module may be used to provide Smartdown's capabilities to an existing application, website, or blog. For an example of how a Smartdown-enabled website can be constructed, see Simple Site Example.

---

Step 5: Review and Share Step 1: GitHub Account

Back to Home

GitHub.md

GitHub

You will create a free GitHub Account

Create a GitHub Account

You will need a GitHub account in order to create new notebooks and share them. If you are currently logged into your GitHub account, then the rest of these directions should work without a problem. If you do not have an account and want to create one, visit Join GitHub. Note that this account is free for the publicly shared content that will become your Smartdown Notebook.

If, for any reason, you can't or wish not to use GitHub to display your content, then consider the other options described in the FAQ.

---

Step 0: Overview of Web Publishing Step 2: Create a New Gist Back to Home

Home.md

Building and Sharing Smartdown Notebooks

REVIEWER NOTE This is an early draft of the tutorial, not intended for wide distribution. I'm hoping to get feedback from my early reviewers (thanks for helping) about how this tutorial could be better targeted towards my audience, who are folks that know the basics of using the web, but are not themselves programmers or web developers. If you are a WordPress author or a programmer, I'd like you to try to imagine that you were instead someone who wanted to blog about something they liked (cooking, travel, art), but had never tried to blog before.

After completing this tutorial, you will have the ability to create a Smartdown notebook that you can share and publish via various forums and blogging systems. This tutorial will focus on using bl.ocks.org and Smartdown Viewer to display your creativity.

Purpose and Intended Audience

This tutorial was written to help folks who are new to bl.ocks.org and/or Smartdown to get started with experimenting and sharing their creations via bl.ocks.org and the Smartdown Viewer. It is not intended to teach Smartdown or show off its full set of capabilities. The focus here is on getting something published, and then counting on you, the author, to improve upon this basic example. For further exploration of Smartdown, I encourage you to explore the Smartdown Viewer, which is full of examples of different Smartdown techniques and applications.

Important Note about GitHub Lag

In some of the tutorial steps that follow, there may be a delay between when you make a change or save a file and when you actually get to see your change. Sometimes, this is a few seconds; at other times, it may be tens of minutes. This is due to delays in the free GitHub service that cannot be controlled; so if it seems as if your changes aren't taking effect, be patient if you can and it will work itself out. Which reminds me of one of my favorite poems...

T.T.T.

Put up in a place where it's easy to see the cryptic admonishment T.T.T.

When you feel how depressingly slowly you climb, it's well to remember that Things Take Time.

• Piet Hein

What you will learn

Follow the steps below, and if everything works out, you will have a new publication that you can edit, refine and share.

• Step 0: Overview
• Step 1: Get a GitHub Account
• Step 2: Make a New Gist
• Step 3: Add Smartdown Essentials
• Step 4: Author Your Content
• Step 5: Review and Share
• Frequently Asked Questions
• Block README

NewGist.md

Creating a Gist

You will create a Gist within GitHub and add a README.md to it.

What is a Gist?

A Gist is a set of files that can be stored within GitHub and shared with others. A Gist is identified with a unique identifier (e.g., ce80e7e99128166167f135a0606d9f01) and its contents can be viewed via a URL like https://gist.github.com/DoctorBud/ce80e7e99128166167f135a0606d9f01.

We will be using a Gist to store several files, which will then be rendered (interpreted and displayed) via a completely different service (unaffiliated with GitHub), Mike Bostock's bl.ocks.org. So we will be using a Gist to store the files that will appear as a Block on a completely different site. It's pretty cool.

Your Gists

Once logged into your GitHub Account, you can view your Gists with the Your gists command. This command is also available via your GitHub account menu in the upper right corner. It looks like this:

If you have previously created a Gist, then Your Gists will show the most recently edited Gists along the top of the window.

A New Gist

The default view of Your gists makes it easy to create a new Gist, and to view and edit your existing Gists, if any. You will also be presented with an empty Gist form that you will populate with content. It should look like this (I've partially filled in the form):

You will be using this New Gist view to create a Smartdown-enabled Gist by adding the following files (don't worry, the details about these files comes later):

• README.md to describe the Block

Describing your Gist

Before getting into the details of adding Smartdown content, let's make sure that you have described your Gist and provided a README.md, which is the minimum amount of effort needed to see something realized on bl.ocks.org. The next card will describe how to edit this checkpointed Gist and extend it with Smartdown content.

In the above screenshot, I filled in the Gist description... input field with the text My First Smartdown Block. You may fill it in with whatever description you choose, and you may change the description later, so don't sweat the decision.

Providing a README.md

Before proceeding to add the Smartdown-specific files to the Gist, you will first add a README.md file that will be used by bl.ocks.org to describe your Block. In the diagram above, I replaced the empty Filename including extension… input field with the name README.md, and I replaced the empty textarea with some initial Markdown content (note that README.md is Markdown, not Smartdown; confusing, eh?).

To simplify the creation of your first Gist, go ahead and paste the Markdown text below into the text input area beneath the README.md filename you entered above. Feel free to adapt it to your message. You can always change it later.

Example README.md text

Copy and paste the following Markdown text into your README.md file in your Gist.

## My Block's `README.md`

This is my first attempt at building a Gist that will become a Block.

I will likely replace this text with something more meaningful in the future.

Save your Gist

Once you've added a Description, and a README.md file, you should save your Gist so that you can proceed with the next phase, where you add the Smartdown-specific content.

To save your Gist, you will need to scroll to the bottom of the page where you are composing your new Gist and you will want to click the Create Public Gist button.

Once you click the button to create your Gist, you will be greeted with a new page that represents your saved Gist. The URL in your browser's location bar will change to something like https://gist.github.com/DrBud/0d86d77875826743680a0d0a1cbe75ed, although the DrBud will be your GitHub username and the 0d86d77875826743680a0d0a1cbe75ed will be a different unique identifier.

View your Gist on bl.ocks.org

Copy the URL from your saved Gist above and edit it by replacing gist.github.com with bl.ocks.org and open the resulting URL, which will (if everything is working OK) be the URL for your new Block. You will notice that your new Block (displayed via bl.ocks.org) will display its Description and the contents of your README.md.

Depending on your browser settings, your Block should look something like this (the text may vary depending upon your choice of Block Description and your README.md, of course):

The next card of this notebook will show you how to extend this basic Block with Smartdown capability and content.

---

Step 1: GitHub Account Step 3: Add Smartdown Essentials Back to Home

NewGistBlock.png

NewGistForm.png

NewGistMenu.png

Overview.md

Overview of Web Publishing

You will understand Author and Reader roles, and what a CMS is.

REVIEWER NOTE I'm experimenting with drawing architecture and schematic diagrams to describe how the GitHub Gists relate to the Author, their Content, and their Web Presence. It's a work in progress. Trying out GraphViz and Mermaid for this purpose.

REVIEWER NOTE This tutorial highlights publication via bl.ocks.org, and only secondarily shows of publication via smartdown.site. I plan on creating a simpler version from this by removing the bl.ocks.org references, focusing on using Gists for CMS and smartdown.site for viewing.

This section is intended for the first-time web author who may want a better understanding of how content is authored and then published via the web. I hope this is also informative for more experienced bloggers and web users.

Author, Reader and Content

To present your creation on the web, you will need a place to put your authored content so that your readers can navigate to a website and see that content displayed or rendered. Such a content management system (CMS) must provide storage for your content, as well as a publicly visible internet address or website so that others can view and interact with your content via their web browsers. Examples of content management systems include wordpress.com and medium.com, and GitHub.com.

The key idea is that when you are in your Author role, creating Content, you will use some sort of service to create or edit your content and store it in the cloud, which basically means that you will put your content into some cloud-based storage system we typically call a Content Management System (CMS). The folks who will consume your content will, in their role as Reader, interact with a website or application that is able to Publish and Display your content in a convenient way.

The following diagram may be helpful in understanding the difference between your source content (e.g., a document named MyDoc.md) and its visibility on the web as a web page (e.g., https://mysite.com/MyDoc).

digraph G {
    graph [fontsize=12 fontname="Verdana" compound=true ];
    node [shape=note fontsize=10 fontname="Verdana"];

    subgraph cluster_0 {
        style=dotted
        label = "Author";
        MyDocAuthor [label="MyDoc.md"];
    }

    subgraph cluster_1 {
        label = "Content Management\nSystem (CMS)\n";
        color=blue;
        Convert [shape=parallelogram, style="dashed", margin=0,
            label="MyDoc.md is converted\n by the CMS\ninto HTML\nand then published"]
        MyDocMD [label="MyDoc.md", style=filled]
        MyDocHTML [label="MyDoc.html", style=filled]
    }

    subgraph cluster_2 {
        style=dotted
        label = "Reader(s)";
        MyDocSite [style=filled, label="https://mysite.com/MyDoc", shape=tab, margin=0.2];
    }

    MyDocMD -> Convert[style=xinvis];
    Convert -> MyDocHTML[style=xinvis];
    MyDocAuthor -> MyDocMD [ltail=cluster_0 lhead=cluster_1];
    MyDocHTML -> MyDocSite [ltail=cluster_1 lhead=cluster_2];
}

The following interaction diagram shows how the Author, Reader and CMS interact:

sequenceDiagram
    participant Author
    participant CMS
    participant Reader

    Author->>+CMS: Here is my latest version of MyDoc.md
    Note over CMS: Store content
    CMS-->>-Author: https://mysite.com/MyDoc has been updated
    Note over CMS: Time passes...
    Reader->>+CMS: I'd like to view https://mysite.com/MyDoc
    Note over CMS: Generate web content
    CMS-->>-Reader: Here's your webpage

Using GitHub and Gists for Web-hosting

For the remainder of this tutorial, you will be using an internet service called GitHub as our Content Management System (CMS), to store and manage your project, as well as to make your content available for viewing via various other portals. GitHub is useful because it is free and because it makes it easy for your content to be used in many ways. For simplicity, we will be using a particular simplified feature of GitHub called Gists, which are designed for single-author content management purposes.

You will use this capability to view your content stored on GitHub via two different viewer websites that can display that content as an interactive Smartdown notebook. Both the bl.ocks.org website and the Smartdown Viewer website have the ability to display GitHub-located content, and it is easy to add this capability to other web-hosting sites such as WordPress, although that is beyond the scope of this tutorial.

---

Step 1: GitHub Account Back to Home

Share.md

Review and Share

You will double-check your notebook and then show it off.

If you've survived the tutorial this far, and everything worked OK, you should now have a notebook consisting of two cards, Home and Playground, and you should be able to click the inter-card links to navigate between the two.

You should also be able to use the triangular Play button to play the P5JS sketch, and you should be able to type in your name into the Smartdown field in the Playground card and see that the sketch changes accordingly. The video clip below shows what your final Smartdown notebook should look like, although there may be some slight differences based upon your browser and font-sizing.

Show off your work

REVIEWER NOTE For this super-secret draft version of the tutorial, please don't share your work widely, as things are still being stabilized. Instead, please share your feedback and your notebook link with me (Dan Keith) via feedback@infoclay.com

You've created your own Smartdown notebook and stored its content as a Gist in GitHub. You know how to view your notebook via bl.ocks.org, in both source mode and raw mode, each of which has its particular features and purpose. You can even use your Gist and view it via the Smartdown Viewer app. Congratulations! How about showing off your work by sharing one of the following links (remember, we are using DrBud/d4b84a34a93ef979123197da0642190f for examples, but you will use your own GitHub username and Gist ID to form a link):

• bl.ocks.org Source Link is useful for displaying the source files for your Notebook.
• bl.ocks.org Raw Link is useful for demonstrating your project without the clutter of the source files and bl.ocks.org.
• Smartdown Viewer Link is useful for showing the source code as well as allowing for local (volatile) editing of that code.
• Smartdown Raw Link is useful for demoing the project without the controls and options in the Viewer.

Using the Smartdown Viewer app

As you experiment with and learn about Smartdown, it will be useful to have a more interactive experience than is provided by bl.ocks.org and GitHub Gists. The Smartdown Viewer is a simple web application that displays a gallery of Smartdown examples and also provides a means for viewing and live-editing of the Smartdown cards within the Gallery. In addition, the Viewer can be used to view local Smartdown files (via drag-and-drop or by using a file selection dialog) and can be used to display any Smartdown notebook that is web-accessible, including the same Gist that you are editing with GitHub and displaying via bl.ocks.org.

To view your Smartdown Gist via the viewer, you will need to get the raw URL for your Home.md. This can be obtained by taking the URL of your Gist and adding the suffix /raw/ to the URL and pasting the result into the Viewer's Load input box (upper right corner). For example, if my Gist URL is: https://gist.github.com/DrBud/d4b84a34a93ef979123197da0642190f then by adding /raw/ I get: https://gist.githubusercontent.com/DrBud/d4b84a34a93ef979123197da0642190f/raw/ Pasting this raw URL into the Viewer will result in it loading the Home.md card from the Gist. Navigation between cards in the Gist will work, as it does in bl.ocks.org.

Viewer is a Work in Progress

Although the current Smartdown Viewer lets you edit the Smartdown text for any of the examples in the gallery, it does not have a way to save these edits. So if you use the Viewer to write a new Smartdown document, be sure to copy/paste your changes. Eventually, the Viewer will have various persistence options, including browser local storage and cloud-based storage (e.g., GitHub, Dropbox).

Other ways to Share

Even though Smartdown is not yet finished, and the syntax may change slightly as it evolves, it is still pretty cool and often a practical choice for splaining something, as I'm doing when I write this tutorial.

This tutorial has focused on using bl.ocks.org to present Smartdown content that is stored within a GitHub Gist. There are several other ways to share and present Smartdown content with your friends, teachers, students and colleagues, and in time this will grow. But the typical way to share will be to place one or more Smartdown files in the cloud and obtain a URL that points to that content. This URL can then be used with the Smartdown Viewer to create a shareable link. This tutorial assumes that the cloud location is a GitHub Gist, but the Viewer works with any Markdown or Smartdown file.

For example, I can refer to a Markdown-formatted document such as the README.md for terinjokes/StickerConstructorSpec by using the raw link https://raw.githubusercontent.com/terinjokes/StickerConstructorSpec/master/README.md as a parameter to the Smartdown Viewer app. For example the link: https://smartdown.site/?url=https://raw.githubusercontent.com/terinjokes/StickerConstructorSpec/master/README.md will load the Markdown content and render it as Smartdown within the Viewer. Of course, if the referenced file is Smartdown, then that would be interpreted correctly.

Feedback

If you successfully complete this tutorial, and especially if you are able to enhance the basic example with your own creativity, I would love to see a link to your Block. If you encountered problems that prevented you from finishing, I'd like to learn what happened. Email me (Dan Keith) at feedback@infoclay.com. Any feedback you have is invaluable; these are early days for Smartdown and there are likely some problems and rough edges. I appreciate your patience and help.

---

Step 4: Author Your Content Frequently Asked Questions

Back to Home

cloud.jpg

index.html

ShareVid.gif

Smartdown.md

SmartdownEdit.png

SmartdownFinal.png

thumbnail.png