Contents

Introduction

Lets take a closer look at the architecture for Squirrel U.

Prerequisites

  • None

GitHub

The Squirrel U project lives in a GitHub Enterprise repository called "squirrel-u" in Zippy's repo. This is the same source control repository SquirrelWorks uses for its source code. This allows us to treat our knowledge content with the same care and diligence that we do our code. This means that content will be version controlled; content will be stored in a central location and go through the same review process that code goes through…And you can do all this disconnected from the network.

Having a diligent review process means that content is reviewed for consistency, accuracy, completeness, standards, etc. before it goes "live". This will allow Squirrel U content to be more "authoritative" in nature. We want Squirrel U to be a place where SquirrelWorks Developers can go to quickly find the information that they need to do a quality job…with the confidence that the information they are getting is accurate, complete and update-to-date.

Markdown

Markdown, abbreviated as md, has been selected as the content medium for Squirrel U. Markdown is a very simple markup language that provides the ability to write plain text content for web pages. There are several different markdown processors; we are using kramdown, which is set in the _config.yml file.

At its core, Markdown is just a super simple way to add formatting like headers, bold, bulleted lists and so on in plain text. Images are also supported to allow for screen shots, diagrams and other visual aids. This helps keep documentation formatting clean and consistent.

Think of all of the various formatting you have seen in Word documents. It usually comes down to personal preference, familiarity with the tool, how much time was available to prepare a document and other factors that come into play when "styling" is a question. Markdown eliminates the guesswork for contributors because it will render content in a consistent manner using a standard syntax.

More details on Markdown and how to create content using this format are provided in the Markdown Overview page.

GitHub Pages

GitHub offers an awesome feature called GitHub Pages, which are web pages hosted and published through the GitHub site. Each time there is a merge in Zippy's repo repository … gh-pages branch, the content is converted through Jekyll (more below). This provides a straight path for curated content placed into GitHub to be automatically built into a website served on GitHub Pages.

Jekyll

So you've heard of Jekyll and Hyde, where the careful Dr. Jekyll turns into the unruly Mr. Hyde. Jekyll takes a more carefully curated and easier-to-maintain set of content written in Markdown and Liquid templates and turns it into HTML, leaving the ugly details to Jekyll to handle. Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites.

Written in Ruby by Tom Preston-Werner, GitHub's co-founder, it is distributed under an open source license.

As you are probably starting to realize, the idea here is to generate static content from a file format that is easier to maintain than traditional HTML. In order to create these static web pages from dynamic components, GitHub uses this parsing engine called Jekyll. Jekyll takes your project and parses it to create its own self-contained static _site folder.

Once generated, these pages are served without any particular backend processing (no server, no database, etc.). It shifts the work from runtime to when the content actually changes, at which point it can be processed in bulk for the whole site.

As mentioned, one appealing element of this parsing engine is that it converts our Markdown files in to HTML. This enables contributors to utilize the more user-friendly Markdown to create their content and Jekyll does the heavy lifting from there.

Also, because the site is being rendered from the static _site directory, that makes it very fast. For example, each time Jekyll regenerates the _site directory, the dynamic searchable material is indexed. So when you enter search criteria, you get a response of matching content almost immediately.

Currently GitHub Pages supports Jekyll 3+. https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0.

To see all Jekyll dependencies and versions: https://pages.github.com/versions/

Rouge Syntax Highlighting

Jekyll uses Kramdown and Rouge for code highlighting. This allows us to specify a code syntax style within three backtick fencing.

This has been setup within Squirrel U using the rougify utility.

Theme Selection
Rougify will build the styling for various presentation themes. Each theme provides styling for a variety of languages.

To see the themes provided

class="highlight">
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class="highlight">
1
class="highlight">
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80