Last weekend I attended CodeStock 2016 and listened to many speakers tout their wares and tell their software engineering stories. One of the most interesting, and entertaining sessions I attended was entitled “Transforming Tribal Knowledge Into Learning Trees” given by Jim D Kohl and his team. I thoroughly expected the talk to be a soft skills lesson on convincing the tribal knowledge sinks to make their knowledge public by some means of documentation. Jim exceeded my expectations completely.
What he presented, by way of a humorous and enjoyable children’s story, was Squirrel-U. It is a set of markdown pages, that are run through gh-pages on GitHub which uses Jekyll to compile the markdown into linked, searchable HTML pages. These pages are not only easy to curate, but also allow for QA by way of the Git repository’s forking and pull request workflows. Jim’s team’s tooling included an on site GitHub instance and IntelliJ, so they were in need on someone to give setup for other IDEs, most notably Visual Studio.
This post will be the first in a series of posts about my journey in configuring Jekyll and Visual Studio to stand up an instance of Squirrel-U in a Microsoft environment instead of a Java/GitHub environment. The goal by the end is to have an instance of Squirrel-U operating on an IIS server, that listens to a Git repository residing in Visual Studio Team Services, and updates itself on the server when approved changes are pushed to the production branch of Squirrel-U.
The first step to the process is just like any other project in Git. Fork the Squirrel-U Git repository located here. If you have never worked with an open source project on GitHub, go here to find directions on forking a GitHub repository, after you create a free GitHub account.
Adding Squirrel-U to a Visual Studio Solution
After you have forked the Squirrel-U Source Code, do the following to set-up the Visual Studio environment (2010 or later) to receive the Squirrel-U code.
- Configure Visual Studio Source Control to use GitHub (if not already done)
- Open Visual Studio from any new or existing project
- Open Tools -> Options -> Source Control -> Plug-in Selection
- Select Microsoft Git Provider
- In Team Explorer Home, select Settings -> Git Settings
- Enter your user name, email address, and default repository location
- Windows Users: Install Git to your machine
- Clone the forked repository to a local repository by doing the following
- Click the Connect to Team Projects icon on the Team Explorer pane
- Expand the Clone drop down under Local Git Repositories
- Fill in the URL for the forked repository.
- Fill in the directory where you want the local repository placed. THIS DIRECTORY SHOULD NOT EXIST YET
- Click Clone to create the local directory and clone the repository.
- Create a new Visual Studio project from Existing Code File -> New -> Project From Existing Code
- Select any project type you want, this does not effect the outcome, Click next.
- Specify the project details as follows:
- Where are the files?: Navigate to the location of the local repository
- Name: Name the project as you see fit.
- Output Type: Class Library
- Click Finish
Install Jekyll on the Local Machine
Too many people have installed Jekyll on a Windows machine before for me to write in depth instructions on how to get Jekyll installed on your development machine. These instructions where very helpful to me. This will get the Ruby SDKs needed, along with Jekyll installed on your local machine. When starting Squirrel-U for the first time, you may get a warning that Jekyll can’t find the gem jemoji. As long as you have Ruby installed in your PATH environmental variable, just type gem install jemoji in the command prompt and it will fix you right up.
Start up Jekyll and see if you can get Squirrel-U started Locally
The following instructions will use Jekyll to build the Squirrel-U site and serve it locally so that you can see how you are doing.
- Open a command window and navigate to the local squirrel-u repository.
- Enter the command
jekyll build --destination <destinationdir>, where
<destinationdir>is the directory that you want the site to be built in.
- Navigate to the
- Start the jekyll server by entering the command
jekyll serveyou should see a message in the terminal saying something similar to the following:
done in 67.513 seconds. Auto-regeneration: enabled for 'C:/git/squirrel-u' Configuration file: C:/git/squirrel-u/_config.yml Server address: http://127.0.0.1:4000 Server running... press ctrl-c to stop.
- You can now go to http://127.0.0.1:4000 and see your squirrel-u running locally!
As long as you have followed these instructions, you should be moving along swimmingly. You now have a Visual Studio Project containing the Squirrel-U source that you can serve locally after running the Jekyll build manually. In the next installment, we will look at installing Grunt.js so that we can keep track of changed files and re-publish Squirrel-U automatically when the pages in specific directories have changed.