Mike Bostock

Let’s Make a Block

This is a quick guide on how to post examples to bl.ocks.org. This is not the only way to do it — you can use GitHub’s Gist editor, for example. But I find this approach convenient because it allows you to preview locally and publish with Git, without leaving the terminal.

#Setup

Most of this guide takes place in the Mac OS X Terminal. If you don’t already have the Terminal in your dock, you can find it in the Applications > Utilities folder. If you’re already comfortable with local web development, go ahead and skip to the next section.

Do you have Node installed already? You’ll use it to preview our code locally, and also to create the gist from the terminal. I recommend Homebrew for installing Node:

brew install node

You’ll also need http-server, a simple zero-configuration web server built on Node for serving content out of the local file system:

npm install -g http-server

If this is your first time using Node, you may also need to edit your PATH so that you can run programs installed by NPM, Node’s package manager. I recommend editing /etc/paths. This file is normally hidden in the Finder, so you won’t be able to open it using File > Open; instead, open it from the terminal. For example, with Sublime Text:

subl /etc/paths

If you don’t already have the subl alias for launching Sublime Text from the terminal, create one like so:

ln -s '/Applications/Sublime Text 2.app/Contents/SharedSupport/bin/subl' /usr/local/bin/subl

Now edit the contents of the file so they look like this:

/usr/local/share/npm/bin
/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

Once you’ve made your changes and saved, close and reopen the terminal to pick up the new PATH.

#Develop

In the terminal, make a new folder for your example, and then cd into that folder.

mkdir example
cd example

Next make an empty file in this folder for your example code, and open the entire thing in Sublime:

touch index.html
subl .

In Sublime Text, you should now see an empty window:

Sublime Text has a bug where if you open an empty folder, saving a new file won’t default to this folder. Opening a folder with at least one file, even if it’s empty, avoids this bug. Hence the touch.

If you want another file, say a README or Makefile, use ⌘N to create it and ⌘S to save it; it will automatically default to the right folder.

Hit ⌘T (Go to File) and start typing "index.html". As soon as index.html highlighted, stop typing and hit return to open it. Paste in the following contents and save (⌘S):

<!DOCTYPE html>
<meta charset="utf-8">
Hello, world!

Back in the terminal, fire up the web server so that you can preview your code in a web browser:

http-server &

The ampersand (&) tells the terminal to run the web server in the background. This means you can continue to use the terminal to run other commands. When you’re all done, you can bring it back to the foreground by running fg, and then interrupt it with ^C (control-C). Or, just close the terminal window.

With http-server running, visit localhost:8080 in your browser and refresh whenever you make changes. Iterate as many times as you like to develop your example, bouncing between your text editor and web browser.

#Publish

Now you need Gistup, another Node program, to create the gist from the terminal. To install:

npm install -g gistup

You can give your gist a description using the -m option, such as gistup -m 'Hello World'. You can also edit the description later by visiting the gist in a web browser. Use gistup -i for interactive mode.

Next, to create the gist from the files in the current folder:

gistup

When gistup completes successfully, it will open the new gist in your web browser. Running gistup for the first time requires creating a personal access token so that you can post to the GitHub API from the terminal; it also requires setting up SSH keys so that you can git push. If you have problems with either of these steps, check the gistup troubleshooting guide.

Now that you’ve made a gist, you can view it on bl.ocks.org! Simply copy the gist number and replace the URL. For example,

https://gist.github.com/mbostock/4060606

becomes

https://bl.ocks.org/mbostock/4060606

You can also install the bl.ocks.org browser extension, which inserts a convenient button on the GitHub Gist page to take you to the corresponding block.

#Update

Want to make further changes after you published? As before, make your changes locally and preview them in your web browser using your localhost web server. Once your changes are ready, commit them using git and push them up to GitHub:

git commit -am 'Made some changes.'
git push

Because bl.ocks.org caches, you may need to wait up to five minutes to see your changes propagate. You can instead visit a specific revision immediately by appending it to the URL (e.g.).

#Advanced Usage

If you add a 230×120 thumbnail.png to your gist, bl.ocks.org will display it on your user page. The only way to add images to your gist (because images are binary files) is using git. See the about page for more ways to customize a block’s appearance.

You can hide certain files from the source view below your example by naming them .*. (For example, .hidden.js.) Binary files and files larger than 50 KB are also hidden.