I have been using GitHub Gist to host some lite d3 projects. My initial motivation was that I can easily convert code snippets to bl.ocks.org. Later I decided to create my own gallery on this blog. The basic page structure is as follows:
<iframe {# visualization } >
Text description
<iframe {# embed code snippets from gist }>
Gist doesn't support directory hierarchy. So I created a project to organize the individual gists and host it on GitHub.
There were couple of problems when I first carry out this plan:
1. The actual codes are hosted on GitHub Gist, and they have different git URLs. Meanwhile, I want each gist to be in a sub-folder of the GitHub project.
2. I want only one copy of the code on my local machine and sync it everywhere (GitHub, Gist, Server).
git submodule command is here to save us all. It seems easy and clear solution right now, I even had a hard time trying to recall what were my problems.
Create Project
First, create project with desired folder hierarchy on local machine. Set up git and push to GitHub remote project.
Second, create gist project. I usually create a short .md file on the gist with capitalized filename. The reason is that gists don't have filename to distinguish from each other. The first capitalized filename (presumably alphabetical order) will be picked up as the title.
Third, navigate to target sub-folder, add gist by using the following example command:
git submodule add https://gist.github.com/26c7ca2499147578411c6d5001700ae3.git single-line-with-tooltip-china-gdp
git submodule add is the command for creating new submodule. It takes two parameters here, https://gist.github.com/26c7ca2499147578411c6d5001700ae3.git is the remote gist URL, and single-line-with-tooltip-china-gdp is the alias to rename the project folder (other than a random 26c7ca2499147578411c6d5001700ae3/).
Repeat second and third steps to add more gists.
Update Project
On the local machine, you can add, edit or delete files as what you normally do. Update gists by commit and push changes within gist root folder. Update the whole project by commit and push changes to GitHub in project root.
d3-demo-by-chart-type # project root
- line-charts
-- single-line-with-tooltip-china-gdp # gist root
- pie-charts
Checkout Project on Other Machines
After the visualizations are ready, I need to checkout the Git project on the server.
Command for update submodules on the first checkout or when directory hierarchy changes:
git submodule update --init --recursive --remote
Update some file changes:
git submodule update --recursive --remote
Remove Git Submodules
Life is about trial and error, especially on your first attempt. Here are the commands to remove the folders from git submodules (credit to Stack Overflow):
# Remove the submodule entry from .git/config
git submodule deinit -f path/to/submodule
# Remove the submodule directory from the superproject's .git/modules directory
rm -rf .git/modules/path/to/submodule
# Remove the entry in .gitmodules and remove the submodule directory located at path/to/submodule
git rm -f path/to/submodule
Leave a comment below if you have any suggestions on other workarounds or improvements.