xD.gov

About

The xD site is a static site built with Jekyll.

Install dependencies

Install Ruby v3 or greater: https://www.ruby-lang.org/en/documentation/installation/

Once Ruby is installed, you can install dependencies contained in the Gemfile via:

bundle install

Bundler is a package manager that comes preinstalled with modern versions of Ruby. You can read more about Bundler here: https://bundler.io/.

Running Code Locally

After cloning the repo, from the project root run:

jekyll serve

If you have errors with the above command, you may need to run Jekyll in a bundler context like so:

bundle exec jekyll serve

Environment Variables

If you need to run the Airtable script locally, create a .env file at the project root with the following format:

AIRTABLE_API_KEY="..."
AIRTABLE_BASE_ID="..."

(contact @curt-mitch-census to get the exact values for these API tokens)

Updating Ruby

If you need to update the version of Ruby, be sure to specify the version both in the Gemfile and .ruby-version file. The later is used by Cloud.gov: https://cloud.gov/pages/documentation/rvm-on-pages/.

Embedding Videos

Currently we can embed YouTube videos (see the 2024 PEPR presentation post for an example). If you want to add videos from other sources see this repository for examples: https://github.com/nathancy/jekyll-embed-video. We include responsive styling suggested in this repo in _news-item.scss.

Code Syntax Highlighting

Syntax highlighting is handled by Kramdown and Rouge. Jekyll Documentation To update the syntax styling, add create a new style from these examples, add it to the folder assets/css/_syntax_highlighting, and import it in assets/css/main.scss.

JavaScript compression

Using the tools Browserify and UglifyJS, JavaScript used in the application can be transformed into a form appropriate for running in a browser (via Browserify) and minified (via UglifyJS) to reduce the bundle size sent to a user's browser.

For example, the D3 map on the Teams page runs through the following CLI commands:

browserify teamMap.js -o mapBundle.js
uglifyjs mapBundle.js --compress --mangle -o mapBundle.js

Analytics

The file _includes/head.html contains script tags for the following analytics tools: Digital Analytics Program Google Analytics