How to Manage D3 Blocks with Git

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:

Initialize the Repo

1. Before beginning, make sure that you have setup ssh keys in your Github account, as https no longer works for accessing the Gist repo from the command line or SourceTree etc. Please see here for instructions
2. Choose "New gist" in menu in the upper right corner on your home page in Github
3. Add a README.md file and add some text (you can add modify later)
4. Click "Create public gist"
5. From the url bar, copy the unique Gist id, for example cfa24192d5d624f702446f194c1a7708 (which happens to be the unique id of this particular Gist)
6. On your Mac, use Terminal/iTerm2 etc, navigate to/create a folder where you'll keep your Gists
7. To clone the just-created Gist, issue the following command (pay attention to the colon) git clone git@gist.github.com:YOUR_UNIQUE_GIST_ID
8. This will create a new directory with the name of the Gist unique id
9. Rename the directory to something sensible
10. Navigate into the just-created directory
11. Verify the remote git configuration with the command git remote -v
12. Open up the README.md file in your text editor, make some changes, then save
13. From the command line, issue the command git status, and you'll see that the README.md file has been changed
14. Stage the file by the command git add .
15. Commit the file with the command git commit -m "Updated README.me"
16. Push the commit to the Gist repo with the command: git push
17. Head back to the Gist session in the browser and refresh the page. You'll see that the content of the README.md file has changed.

Create Your D3 Block

1. These are the requirments of a D3 Block: a) There must be an index.html with a max window size of 960x500 pixels, b) there should be an README.md file that describes your visualization, and c) there can also be a thumbnail.png file with the size of 230x120 pixels
2. The index.html file in this Gist repo loads three files:
   • The styles.css file which configures the window to the correct size for a D3 Block
   • A current version of d3 from a CDN (Cloudflare),
   • The index.js file. The file is currently almost empty (only console logs the d3 version). Put your visualization code in this file. The file is loaded by the index.html with the defer attribute, so the DOM is fully loaded by the time the index.js begins execution
3. Develop your visualization locally, by editing the index.js file. Test your work in process by opening up the index.html file in your browser. Keep iterating until done
4. 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 command git commit -m "Commit message..." (customize the commit message to describe the actual work you're committing)
5. Push the commit to the Gist repo with the command: git push
6. 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
7. 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
8. 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/