Skip to content

Latest commit

 

History

History
103 lines (77 loc) · 3.78 KB

infrastructure.md

File metadata and controls

103 lines (77 loc) · 3.78 KB
Raw
title description
Infrastructure
Infrastructure

Infrastructure

Git submodule

Sites making use of site-shared include it as a git submodule of the same name at the site repo's root.

To use a specific site-shared resource, you'll generally create a symlink to the desired resource file. In some cases, you'll needed to adjust the site _config.yml. Details are given below.

Jekyll

We use the Jekyll site generator, leaving most of its configuration options at their default settings, including use of Kramdown as the markdown processor and Rouge as the default syntax highlighter.

To see a list of the languages you can use with ```, see Rouge's list of supported languages and lexer. The most common languages we use are dart, console (or its equivalent, terminal), nocode, and yaml.

Ruby gems and the bundler

Jekyll is written in Ruby, so we use the bundler (the equivalent of Dart's pub) to manage gems (the equivalent of pub packages). Each site's Gemfile specifies the gems it uses, possibly constraining gem versions (similar to what you'd do using a pubspec.yaml file). The bundler creates a Gemfile.lock which (transitively) lists the gems and gem versions actually used for the site.

Note: The bundler gets installed using tool/before-install.sh.

For optimal sharing of resources across sites, ensure that the sites' Gemfiles are kept as in sync to the extent practical / possible.

Jekyll plugins

The main third-party Jekyll plugins we use are the following:

  • jekyll-assets, for asset management. Assets are the site files under src/_assets. For production builds, jekyll-assets does asset file finger-printing. This ensures that resource file caching won't interfere with the release of new asset versions since each asset file is suffixed with a hash determined from the file content.
  • jekyll-toc for autogeneration of page table of contents.

We share custom plugins across sites. These can be found under src/_plugins. To use a shared plugin, create a symlink from the plugin in site-shared/src/_plugins to the repo's src/_plugins folder.

Assets

You can tell jekyll-assets where to look for shared assets (like CSS and JS files) by adding the following lines to a site's Jekyll config file (_config.yml):

assets:
  sources:
    - _shared/_assets
    - _shared/_assets/css

This assumes that you've setup a single symlink to the site-shared submodule by running the following commands (from the repo root):

$ cd src
$ ln -s ../site-shared/src _shared

Once this is setup, then you can simply "include" site-shared assets like CSS files (such as src/_assets/css/_code_pre.scss) like this:

@import '_code_pre';

JavaScript can be similarly imported:

//= require vendor/jquery-3.6.0

Note: //= require is jekyll-assets include syntax.