There are several ways to create and manage D3 Blocks at bl.ocks.org. The easiest is probably to use Blockbuilder. One can also copy/paste code directly into the Gist ui at gist.github.com.
However, if you want to use git from from the command line to manage your Blocks (just like you manage your regular Github repos), follow these steps:
- Before beginning, make sure that you have setup
sshkeys in your Github account, ashttpsno longer works for accessing the Gist repo from the command line or SourceTree etc. Please see here for instructions - Choose "New gist" in menu in the upper right corner on your home page in Github
- Add a
README.mdfile and add some text (you can add modify later) - Click "Create public gist"
- From the url bar, copy the unique Gist id, for example
cfa24192d5d624f702446f194c1a7708(which happens to be the unique id of this particular Gist) - On your Mac, use Terminal/iTerm2 etc, navigate to/create a folder where you'll keep your Gists
- To clone the just-created Gist, issue the following command (pay attention to the colon)
git clone [email protected]:YOUR_UNIQUE_GIST_ID - This will create a new directory with the name of the Gist unique id
- Rename the directory to something sensible
- Navigate into the just-created directory
- Verify the
remotegit configuration with the commandgit remote -v - Open up the
README.mdfile in your text editor, make some changes, then save - From the command line, issue the command
git status, and you'll see that theREADME.mdfile has been changed - Stage the file by the command
git add . - Commit the file with the command
git commit -m "Updated README.me" - Push the commit to the Gist repo with the command:
git push - Head back to the Gist session in the browser and refresh the page. You'll see that the content of the
README.mdfile has changed.
- These are the requirments of a D3 Block: a) There must be an
index.htmlwith a max window size of 960x500 pixels, b) there should be anREADME.mdfile that describes your visualization, and c) there can also be athumbnail.pngfile with the size of 230x120 pixels - The
index.htmlfile in this Gist repo loads three files:- The
styles.cssfile which configures the window to the correct size for a D3 Block - A current version of d3 from a CDN (Cloudflare),
- The
index.jsfile. The file is currently almost empty (only console logs the d3 version). Put your visualization code in this file. The file is loaded by theindex.htmlwith thedeferattribute, so the DOM is fully loaded by the time theindex.jsbegins execution
- The
- Develop your visualization locally, by editing the
index.jsfile. Test your work in process by opening up theindex.htmlfile in your browser. Keep iterating until done - Then, head to the command line and stage the file(s) with the command
git add .(please note the period). This command which will stage all changes (and any additional files that you may have added). Commit the staged file(s) with the commandgit commit -m "Commit message..."(customize the commit message to describe the actual work you're committing) - Push the commit to the Gist repo with the command:
git push - Or better yet, keep staging/committing/pushing while you are developing the viz, so you don't risk loosing your work. By committing frequently, you can also revert back to an earlier working version, should your viz no longer work of whatever reason
- At some point, head to the Gist page with your browser and refresh, you'll see all the updated files (
index.html,index.js,styles.css) and any other files that you may have added - Then head to
https://bl.ocks.org/YOUR_GIT_ID. After a few minutes you should be able to see your new Block!
Additional Resources:
https://bl.ocks.org/emmasaunders/2ac8e418958f4c681f229f82729c9647 https://miningthedetails.com/blog/d3/CreatingD3Blocks/
