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.
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:
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
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:
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:
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.
Now you need Gistup, another Node program, to create the gist from the terminal. To install:
npm install -g gistup
Next, to create the gist from the files in the current folder:
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,
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.
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.).
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
You can hide certain files from the source view below your example by naming them
README.*. (For example,
README.js.) Binary files and files larger than 50 KB are also hidden.
If you make lots of examples, it helps to mirror the URL structure of bl.ocks.org on your local file system. This way you can reference files that are stored in other gists using relative links. Your local folder structure should look something like this:
mbostock/ raw/ 4060606/ index.html 4090846/ us.json
If you share common files across gists, you can update them in one place rather than duplicating them every time you make a new example. See this technique at work in the basic choropleth.