howto-build-github-pages-locally.md

How to build GitHub Pages locally

Introduction

The GitHub pages are only built when a commit is added to the latest-release branch. This makes the process of testing the HTML rendering of local changes difficult.

This document describes one process to build the GitHub page locally.

Script

The script build-github-pages.sh contained in this same directory automates this process.

Prerequisites

• Docker.
• Make.

Note: it has only been tested on Linux.

Guide

1. Clone GitHub Pages Ruby Gem.
2. Follow the first step on their page to build the Docker image:
   • make image.
3. The build process uses Jekyll to transform Markdown files into HTML. On top of that, the official GitHub Pages build process enables some plugins for it that are not included by default in the local build process. Thus we must enable them manually:
   • Open _config.yml in the root of the ACLE directory.
   • Add the following to the end of the file (list taken from here):

     plugins:
     - jekyll-coffeescript
     - jekyll-default-layout
     - jekyll-gist
     - jekyll-github-metadata
     - jekyll-optional-front-matter
     - jekyll-paginate
     - jekyll-readme-index
     - jekyll-titles-from-headings
     - jekyll-relative-links

4. Follow the second step on their page to build the pages with Jekyll and run a web server:
   • SITE=PATH_TO_ACLE_DIRECTORY make server.
5. On the terminal output, the IP and port of the web server will be shown. Just open it in a browser.

Incremental builds can be done by starting at step 4.