- Technologies / dependencies
- Built with
- Front end:
- Linting
- Deployment
- Prerequisites:
- Project setup
- Design Tokens
- Component-centred design and the Fractal living styleguide
- Search integration
- Commands
- Run dev server
- Building for production
- Building the living styleguide to static HTML
- Secondary tasks
- Linting
- Hosting, release and deployment
- Hosting
- Creating a new release
- Deployment
- Project structure
- Configuration
- Jekyll
- Vue CLI
- Hacks
- Other useful bits
- Jekyll - static site generator
- Vue CLI - webpack-based build process
- Fractal Living styleguide
- git flow as a branching methodology
- Theo for managing Design Tokens
Linting is enforced on a pre-push hook via Husky. This can be disabled / modified via package.json
- Deployed and hosted with Netlify
- NodeJS runtime - ~10.x.x LTS release:
- Yarn
- Ruby 2.3.0 or greater
- bundler
- git-flow extensions (only required for release)
git clone git@github.com:theodi/open-standards-guidebook.git
cd open-standards-guidebook
cp .env.example .env
Now populate Algolia environment variables in .env
see Deployment, then
yarn install
bundle install --path vendor/bundle
yarn serve
This project uses Design Tokens to manage shared values such as colours, font families, breakpoints and other size values, so that they can be shared easily accross projects and formats ((S)css, JS) while maintaining a single source of truth.
That single source of truth is held in Design Token files (spec) in the design/
directory.
The project uses the YAML formatting option for its design tokens for both ease of use and consistency with Jekyll metadata
This project takes a component-based approach to its design and development. Components are located in the assets/styles
directory and are documented using the Fractal living styleguide tool.
Components are implemented in Fractal in the first instance, using the styleguide as a "workbench" to develop and test components and content scenarios for them before they are integrated into the Jekyll site.
NB As a Liquid templating adaptor was not available for Fractal at the time of development, the Fractal templates are written using the very similar but not identical Twig templating language
Search is provided via Algolia, using jekyll-algolia to index the site at build time in Netlify, and Algolia's vue-instantsearch library to build the reactive JS search UI. Because of the static nature of the site, there is no fallback search for users without JavaScript.
All commands are via node package scripts.
yarn serve
This command does several things concurrently:
- Starts jekyll server with
JEKYLL_ENV=development bundle exec jekyll serve --config _config.yml,_config.dev.yml
onlocalhost:4000
- Starts a vue-cli / webpack asset server on a port defined in
package.json
underbuildConfig.ports.assets
- Starts the Fractal styleguide on a port defined in
package.json
underbuildConfig.ports.assets
You can run/debug each of these tasks separately via:
yarn serve:jekyll
yarn serve:assets
yarn serve:fractal
(the top level yarn serve
task runs each of these tasks concurrently with one another)
yarn build
- Compiles the design tokens via Theo
- Builds the revved assets via
yarn build:assets
- Builds the Jeykll site via
yarn build:jekyll
/JEKYLL_ENV='production' bundle exec jekyll build
The built site is output to dist/
, which is used as the web root directory on deployment
You can run/debug each of these tasks separately via:
yarn build:design-tokens
yarn build:assets
yarn build:jekyll
You can compile the Fractal styleguide to static HTML via
yarn build:fractal
This will build the styleguide to a styleguide/
directory in the project root
Linting (via yarn lint
) is enforced on a pre-push hook via Husky. This can be disabled / modified via the husky
key in package.json
.
JS files are also linted at Babel compile time via eslint-friendly-formatter
.
The following tasks are available for your manual linting requirements:
yarn lint:styles
yarn lint:js
yarn lint:html
yarn lint # all the things
yarn build:fractal
This builds the Fractal styleguide to static HTML and outputs it to a styleguide/
directory (gitignored) in the project root.
yarn lint:html
This runs html-proofer with options configured via a rake task.
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:
Required:
- comment out the
url
andbaseurl
keys. 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'surl_swap
feature, but we have not currently got that working correctly.
Optional:
- Change
env
todevelopment
(not required but will disable html minification making the build much faster)
The site is hosted on Netlify, and is configured to build automatically on push to the master
branch of the GitHub repo, via the Netlify GH app.
A release script is included for convenience. Use a semver compliant version.
yarn project:release
This will:
- Prompt for the release type
- Create a new release branch from
develop
- Bump the
version
key inpackage.json
and commit it - Merge back into
develop
andmaster
- Tag the release
- Push the release and tag to
origin/master
NB Release script requires git-flow
cli to be installed locally.
Netlify is configured to automatically build the site on push to the master
branch of the GitHub repo, via the Netlify GH app.
An environment variable of JEKYLL_ENV=production
is set via the Netlify web UI in order to trigger Jekyll to use the production configuration when building the static pages for the site.
Additionally the following environment variables are set to enable the Algolia integration:
ALGOLIA_API_KEY
ALGOLIA_APPLICATION_ID
ALGOLIA_INDEX_NAME
ALGOLIA_SEARCH_API_KEY
Values for all these can be found in the Algolia dashboard under API keys, with the exception of the Application ID, which is listed in the sidebar of the Algolia UI.
The command run by netlify is:
yarn build && yarn algolia:index
Which unpacks to:
yarn build:design-tokens # Compile the abstract design tokens to scss/json
yarn build:assets # Build the Image, CSS and JS assets for the site via webpack / Vue CLI
yarn build:jekyll # Build the site's HTML via Jekyll
yarn algolia:index # index the built site in Algolia
├── _config.dev.yml # Jekyll dev config - loaded in addition to _config.yml
├── _config.yml # Main Jekyll config
├── _templates/ # Generator templates for front end components - ignore!
├── assets/ # Front end assets - consumed by build process
│ ├── styles/ # Components for Fractal styleguide
│ ├── images/ # images - filenames will be revved on build so use rev filter in liquid
│ ├── js/ # JavaScript goes here, use ES6 as transpiled with webpack
│ └── docs/ # Markdown formatted documentation for Fractal styleguide
│
├── dist/ # Built site goes here
│
├── jekyll/ # The Jekyll part of the project
│ ├── _data/ # Data files in yml, primarily used for nav generation
│ ├── _includes/
│ ├── _layouts/
│ ├── _plugins/ # Custom plugins - currently just rev_filter for asset manifest parsing
│ ├── _templates/
│ ├── about/ # site content
│ ├── assets/ # Output dest for blendid build - ignored in git
│ ├── community/ # site content
│ ├── creating-impact/ # site content
│ ├── creating-open-standards/ # site content
│ ├── find-existing-standards/ # site content
│ ├── guide/ # site content
│ ├── index.md # Homepage
│ └── introduction /# site content
(Some files / dirs removed above for clarity)
See inline documentation in _config.yml
/ _config.dev.yml
for details.
Additionally, We are using the following Jekyll third-party plugins, auto installed via the :jekyll_plugins
group in Gemfile
.
- 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
We also have the following custom Jekyll plugins (in jekyll/_plugins
)
- env_vars.rb - exposes environent variables (inc from
.env
) to Jekyll - rev_filter.rb - supports revving asset file names via a manifest.json file output by the asset build process
The asset build process is configured / customised via the vue.config.js
in the project root.
- The
jekyll-git_metadata
is monkey patched insrc/_plugins/git_metadata.rb
to handle the fact that we're running Jekyll in a subdirectory of the project
- Regenerate the table of content for this README.md (or any other) by running
yarn docs:toc
and pasting in the output