Open Standards Guidebook
Table of Contents
- Technologies / dependencies
- Project setup
- Release and deployment
- Project structure
- Contributions application
- Other useful bits
Technologies / dependencies
- Jekyll - static site generator
- Blendid - Gulp + webpack build process
- Fractal Living styleguide
- Theo for handling Design tokens
- git flow as a branching methodology
- Sass for stylesheets (compiled with node-sass)
- Babel for JS transpilation
- Browsersync for live reloading
Linting is enforced on a pre-push hook via Husky. This can be disabled / modified via
- NodeJS runtime - ~8.9.3 LTS release:
- Ruby 2.5.0 or greater
- git-flow extensions (only required for release)
git clone email@example.com:theodi/open-standards-guidebook.git cd open-standards-guidebook yarn install bundle install cd contributions && bundle install # install the deps for the the contributions form app cd ..
All commands are via node package scripts.
Run dev server
This command does several things concurrently:
- Starts jekyll server with
JEKYLL_ENV=development bundle exec jekyll serve --config _config.yml,_config.dev.ymlon
- Starts a browsersync proxy of the same server, typically on
localhost:3000(actual port will be shown when starting the command). This is used to live inject the styles (via browsersync) and JS (via webpack hot reload)
- Starts the Fractal styleguide server (typically on http://localhost:4001/, see command output for your case)
- Starts foreman to run the contributions Sinatra application
It will also open the Fractal styleguide and browsersync proxied Jekyll build in your default web browser. Additional Browsersync UI tools available on port 3001.
Building for production
This builds the assets via blendid and then runs
JEKYLL_ENV='production' bundle exec jekyll build
Compiles files for production to your destination directory. JS files are built with webpack 3 with standard production optimizations (uglfiy, etc.). CSS is run through CSSNano.
rev is set to
true in your
task-config.js file, filenames will be hashed (file.css -> file-a8908d9io20.css) so your server may cache them indefinitely. A
rev-manifest.json file is output to the root of your
dest directory (
public by default), and maps original filenames to hashed ones. Static files are automatically updated to reference the hashed filenames. A custom Jekyl plugin (rev) is used to to read the manifest file and replace references to static asset filenames via a liquid filter.
yarn lint) is enforced on a pre-push hook via Husky. This can be disabled / modified via
JS files are also linted at Babel compile time via
The following tasks are available for your manual linting requirements:
yarn lint-styles yarn lint-js yarn lint # all the things
Building styleguide as static HTML
This builds the Fractal styleguide to static HTML and outputs it to a
component-library/ directory (gitignored) in the project root.
Check HTML links (WIP)
This task is currently designed to be run locally (i.e. not in CI)
Because we're currently deploying the site to a subdirectory, it also requires some temporary changes to
_config.yml or it will throw a large number of false positives:
- comment out the
baseurlkeys. This is required so that Jekyll writes out links in a way that html-proofer can resolve. This can probably be worked around using html-proofer's
url_swapfeature, but we have not currently got that working correctly.
development(not required but will disable html minification making the build much faster)
Release and deployment
A release script is included for convenience. Use a semver compliant version.
- Create a new release branch from
- Bump the
VERSIONfile and commit it
- Merge back into
- Tag the release
- Push the release and tag to
NB Release script requires
git-flow cli to be installed locally.
(Some files / dirs removed above for clarity)
See inline documentation in
_config.dev.yml for details.
Additionally, We are using the following plugins, auto installed via the
:jekyll_plugins group in
jekyll-git_metadata - Git metadata for last edited dates on oages octopress-minify-html - Minifies HTML on build only jekyll-sitemap - XML sitemap generator jekyll-seo-tag - SEO metadata generation
You may override the default configuration via editing
task-config.js in the
build/ directory. See the separate
README.md and inline documentaton in that directory for full options available.
contributions/ directory contains a small Sinatra application that takes form submissions and turns them into issues / PRs on the GitHub repo via the GH api. For full details of this component of the project see
jekyll-git_metadatais monkey patched in
src/_plugins/git_metadata.rbto handle the fact that we're running Jekyll in a subdirectory of the project
Other useful bits
- Regenerate the table of content for this README.md (or any other) by running
./scripts/gh-md-toc README.mdand pasting in the output