Configure Jekyll for graceful local development

[brianzelip]

The current Tech Docs site seems to rely fully on GitHub Pages for building and deployment. It doesn’t provide a local development environment.

This PR provides the basis for opting-in to local development and building the Tech Docs site, while maintaining the ability to edit content directly on github.com, or by any other means. Deployment is still handled via GitHub Pages.

This is the first step in adding a fresh coat of paint to the tech docs.

Closes #153

TL;DR

This PR adds the ability to opt-in to local development; it does not change the current user experience of reading the docs, nor the current contributor experience of updating the docs.

Create local dev environment

Requires Ruby and Bundler.

1. Install dependencies

bundle install

2. Build and serve

bundle exec jekyll serve

Serves on localhost:3000. See Jekyll docs for more options.

Live demo

See this PR in action at https://brianzelip.github.io/tech-docs-jekyll/

What changed?

Settings

• Gemfile, Gemfile.lock: define the local environment; Gemfile was modified from the output of running jekyll new
• _config.yml:
  • explicitly configures jekyll-optional-front-matter plugin to recreate its use by GitHub Pages behind the scenes, which allows us to not have to add empty front matter to every .md file which Jekyll would otherwise require
  • explicitly adds a default layout to all pages which GitHub Pages provides behind the scenes
  • adds site metadata, including GitHub Pages-provided data
• .gitignore: ignore jekyll artifacts

Content

• set permalink front matter for all README.md files meant to act as index.html files, which GitHub Pages provides behind the scenes
• fix internal links pointing to .md files by pointing to .html files, which GitHub Pages provides behind the scenes

[searcy]

Thanks @brianzelip -- this looks great.