Build the documentation site

Last updated:
Edit on GitHub

We use Jekyll to build the Spryker documentation site. To build it locally, you need to:

  1. Install Jekyll
  2. Set up the documentation site locally
  3. Run the documentation site locally

Install Jekyll

Depending on your operating system, follow the Jekyll installation guides below.

Install Jekyll on MacOS

The installation process is different depending whether you are using a Mac with an Intel processor or with a Silicon M1 chip. To find out whether you have an Intel or a Silicon M1 Mac, click the Apple menu and choose About This Mac.

  • Silicon Macs with the M1 processor show an item labeled Chip followed by the name of the Apple chip.

  • Intel-based Macs show an item labeled Processor followed by the name and/or model number of the Intel processor.

MacOS on M1 processor – Open Terminal using Rosetta

On a MacBook with the M1 processor, make sure your Terminal is opened with Rosetta 2, by following the instructions here. Rosetta is a translation layer that enables non-native Intel x86 apps, including Homebrew, to run on Apple Silicon Macs. To open your terminal using Rosetta, follow these steps:

  1. Open a Finder window.
  2. In Applications, locate Terminal.
  3. Right click on Terminal and select Get Info.
  4. Make sure Open using Rosetta is checked.

On either an M1 or an Intel Mac, follow the steps below to install Jekyll. M1-specific instructions appear as notes wherever necessary.

1. Install Homebrew

Homebrew is a package manager for macOS because by default Mac doesn’t have a package manager. You use Homebrew to install Ruby in the next step. Additionally, when you install Homebrew, Xcode command line tools and GCC are also installed automatically.

To install Homebrew, follow these steps:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
MacOS on M1 processor

On an M1 Mac, Homebrew files are installed into the /opt/homebrew folder. Because this folder is not part of the default $PATH, you need to follow the next steps that Homebrew includes at the end of the installation output to add Homebrew to your PATH. In the example below, we’ve replaced your actual username with: /Users/_username_/.zprofile.

==> Next steps:
- Run these three commands in your terminal to add Homebrew to your PATH:
    echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/_username_/.zprofile
    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/_username_/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"

Alternately, or if you have problems using these commands to update your PATH, you can add Homebrew to your .zprofile file. First, run the following command:

nano ~/.zprofile

If the profile file has not yet been created on your system, this command creates a new one. If the file already exists, this command opens it.

To add Homebrew, paste this text into the .zprofile file open in your terminal:

# Set PATH, MANPATH, etc., for Homebrew.
eval "$(/opt/homebrew/bin/brew shellenv)"

To save the updated .zprofile file, click control o. Then, to exit the .zprofile file, click control x.

2. Install Make

brew install make

3. Install Ruby

Check your current Ruby version:

ruby -v
Don't use system Ruby

You should not use the Ruby version that came pre-installed with your Mac. Apple includes an older, non-updatable version of Ruby on macOS for compatibility with legacy software.

If you have not yet installed a recent Ruby version, install Ruby:

brew install ruby

Add the brew Ruby and gems path to your shell configuration:

  1. Check what shell you are using:
    echo $SHELL
  2. Depending which shell you are using, add the path using one of the following commands:
    • Zsh: 
      echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc
    • Bash: 
      echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.bash_profile

3. Install Jekyll and Bundler

  1. Install Jekyll and Bundler gems:
gem install --user-install bundler jekyll
  1. Check the installed Ruby version:
ruby -v
  1. Append your path file with the following, replacing X.X with the first two digits of the Ruby version you’ve checked in the previous step:
    • Zsh:
    echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.zshrc
    • Bash:
    echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

Install Jekyll on Windows, Ubuntu, or other Linux systems

Prerequisites

To use Jekyll on Windows, Ubuntu, or other Linux systems, you also need to install the following:

  • Ruby version 2.4.0 or higher, including all development headers. To check your version, run ruby -v.
  • RubyGems, the latest version. To check your RubyGems version, run gem -v.
  • GCC and Make. To check your GCC version, run gcc -v,g++ -v, for Make version run make -v.

Install Jekyll on Windows

To install Jekyll on Windows, follow the official Jekyll on Windows documentation.

Install Jekyll on Ubuntu

To install Jekyll on Ubuntu, follow the official Jekyll on Ubuntu documentation.

Other Linux systems

To install Jekyll on other Linux systems, follow the official Jekyll on Linux documentation.

Set up the Spryker documentation site locally

To set up the Spryker documentation site locally:

  1. Clone the Spryker documentation repository and go to the newly created directory:
git clone git@github.com:spryker/spryker-docs.git ./spryker-docs
cd spryker-docs
  1. Install all the necessary dependencies with Bundler:
bundle install
MacOS on M1 processor

On a MacBook with the M1 processor, run the following command instead:

arch -arch x86_64 bundle install

Run the documentation site locally

To run Spryker documentation site locally:

  1. Go to the local documentation site directory:
cd spryker-docs
  1. Build the site:
bundle exec jekyll serve

Now, you can access the local copy of the Spryker documentation site at http://localhost:4000.

MacOS on M1 processor

On a MacBook with the M1 processor, run the following command instead:

arch -arch x86_64 bundle exec jekyll serve

Tips and tricks

  • To regenerate only those pages that were added or updated since the last build, build the site with the following command:
bundle exec jekyll serve --incremental
  • To automatically refresh the page with each change you make to the source files, build the site with the following command:
bundle exec jekyll serve --incremental --livereload