Contributing to Our Website

Purpose

Some of the best ways to contribute to Innolitics outside of client work—writing articles, improving our training program, or polishing our handbook—involve updating our website. This lesson will introduce you to Jekyll, the static site generator that produces our website, and show you how you can contribute to website updates.

Learning Material

Read through our article writing process.

Skim through the Jekyll documentation. The pages within the “CONTENT” and “SITE STRUCTURE” sections are especially relevant.

Keeping your understanding of Jekyll in mind, skim through our website’s source code.

Exercises

We recommend that you write your response to each question, before revealing the provided answers.

Exercise 1

Why do we write articles for our website?

Provided Answer

We write articles to help us pursue our company mission of sharing knowledge and to accord with our company values of learning.

More specifically:

  1. Individual Learning – Writing about a topic is one of the best ways to learn about it
  2. Sales – Sales leads will see that we are expert software developers
  3. Marketing – Content will improve our search ranking, helping clients find us
  4. Team Learning – To produce educational resources for other developers on our team

Exercise 2

What is a static site generator?

Provided Answer

A static site generator is a type of website generator that renders static HTML files to be hosted on the browser. In contrast, a dynamic site generator creates a new HTML file each time the user requests a page.

To better understand this, consider ordering at a restaurant. You make a custom order, and the chef cooks the dish after receiving your request. You ask for soda, so the waiter delivers a can. In this example, the chef is like a dynamic site generator, preparing something only when a request is made. The can of soda is like a static site: its contents are fixed and it was ready to serve before any requests were made.

Using a static site generator has many benefits, most notably the speed at which the pages are served to the user.

Gatsby is another popular static site generator. (Gatsby’s components are a nice improvement over Jekyll’s includes.)

Exercise 3

Trace, in detail, how the raw YAML, HTML, and other source files for our website are transformed into the compiled files that are served when you visit “innolitics.com”. Note that we use GitHub Pages to serve the files. Before opening the answer try reading Jekyll source code to trace the path for transforming source files.

HINT
What is the first step to start running Jekyll on our website directory?

Run jekyll in the command line.

Where is the Jekyll executable defined in the source code?

The jekyll command is located in the exe folder of Jekyll source code. Read through this file and think about the following:

  • What is happening with Jekyll::Command?
  • What is the subclasses method, and where is it defined?
  • Do you notice any other functions in the file where subclasses is defined that might help us understand how Jekyll builds static files from raw source files?
HINT

What does a config file do? Do you see a method that runs configuration options?

Provided Answer

We use GitHub Pages to build and serve the site. Thus, when we push a change to the master branch, GitHub’s servers will run jekyll build and will compile our raw source files into a set of static HTML, CSS, and other files for it to server.

How does jekyll build work?

  • We begin with the Jekyll executable
  • From there, it determines the subcommand to run
  • It runs the build subcommand
  • The build subcommand uses the commandline arguments and the _config.yml file to produce an in-memory representation of the Jekyll config.

Exercise 4

Set up a development copy of the website. When you execute the ./run script, a browser tab with our website should open at 127.0.0.1:4000.

HINT

Read through the README and be sure the system dependencies have the appropriate versions.

Read about our standard script names.

Exercise 5

Find a typo, a broken link, or an opportunity to improve the wording somewhere on our website. Create a pull request to fix this.

Improvements and Completion Pull Request

Using a local copy of the website, start a git branch.

Remove any exercises or learning material that are not useful to the intended audience. Find ways to shorten and clarify the writing. Add generally useful exercises, responses, or learning material. Your improvements will make our training program great!

Add your self to the "completed" property in the lesson's YAML front matter.

Create a pull request and assign it to your lesson mentor (e.g., David). They will review and set up a time to talk through the lesson. After the lesson merge in your changes.