Instructions for using Jekyll and working locally on the Stitch Docs.

Prerequisites

• You have installed all the tools needed to build the site. For more information, see the Installing the prerequisites.

Step 1: Build a local version of Stitch Docs

Run the following command in the Stitch Docs repository to build the site locally:

jekyll build

If you encounter issues with jekyll build, try:

bundle exec jekyll build

Step 2: Spin up a local Jekyll server

After you’ve built the site (jekyll build), you can spin up a local Jekyll server to preview your changes as you make them.

In the command line, run the following:

jekyll serve

If you encounter issues with jekyll server, try:

bundle exec jekyll serve

Enable incremental regeneration

You can also enable incremental regeneration to help shorten build times. This will significantly reduce the amount of time it takes for Jekyll to refresh the local server when changes are made.

Because the Stitch Docs is quite a large site, using this configuration option is the most efficient way to work locally.

To enable it, add the --incremental flag when spinning up the server::

bundle exec jekyll serve --incremental

Note: Incremental regeneration will only regenerate files where direct changes are made - that is, directly to a page file or an include. Changes to data files will only be detected when the file using them is also saved.

Step 3: Navigate to the site in a browser

After the server is finished generating (indicated by Server running... press ctrl-c to stop.), open up a browser and browse to localhost:4005/docs.

Note: To see your changes, you’ll need to refresh the page in the browser.

Step 4: Understanding the build process

When Jekyll builds the site, it performs several operations:

SASS compilation

Jekyll automatically compiles SASS files from the sass/ directory into stylesheets/screen.css. The SASS compilation settings are defined in _config.yml:

sass:
  sass_dir: _sass
  style: expanded

The compiled CSS includes source map comments that reference the original SASS files, making it easier to debug styling issues. For example: /* line 49, ../sass/_changelog.scss */

Important: Never edit CSS files in stylesheets/ directly - they are auto-generated. Always make style changes in the sass/ folder.

Markdown processing

Jekyll uses Kramdown with GitHub Flavored Markdown (GFM) to convert markdown files to HTML:

markdown: kramdown
kramdown:
  input: GFM
  hard_wrap: false

Liquid templating

Jekyll processes all Liquid tags and includes, combining templates from _includes/ and _layouts/ with content from collection files and data from _data/ to generate the final HTML pages.

Step 5: Deployment to production

The Stitch Docs are deployed to production using Netlify, which automatically builds and deploys the site whenever changes are pushed to the master branch.

Deployment workflow:

1. Changes are merged to the master branch on GitHub
2. Netlify detects the push and triggers an automatic build
3. Netlify runs jekyll build to generate the static site
4. The built site is deployed to production

Note: No manual build or deployment steps are required. The entire process is automated through Netlify’s GitHub integration.

Last updated: 27 April 2026