Back to blog home page

Generating a Jekyll Static Site with GulpJS

Posted by on Jan 05, 2016

Jekyll is a static site generator that takes a collection of content pages, and assets such as images, and generates a website.

A Documentation Web Site

In an open-source project, it is natural to extend the prototypical README to a more extensive documentation of anything ranging from architecture, to design, to usage instructions, to user manual. A README is fine, but once it gets too long, it is best to structure it into folders by subject. A large enough system would require also media assets, such as images.

Coming from the README origin, it is natural to use Markdown to write the documentation.

Such a documentation collection to be useful for readers has to be presented as a website that provides its readers with common HTML pages presentation, including search capability, and showing media assets on pages.

A Static Site Generator

We would like to generate such a documentation website automatically from a documentation folder, and its subfolders, containing Markdown files and media assets.

Most often, the documentation is spread across multiple folders of software projects, and we need to automatically extract the Markdown files and images.

Jekyll is convenient as the target static site generator because it can handle Markdown, and through a plugin provide full-text search capability.

But we needed an automated way to provide the source content to Jekyll.

Gulp to the Rescue!

Gulp is workflow automation system built on the principle of pipelining files between tasks.

Our tasks pipeline:

  1. Extract Markdown files (with .md extension) from our project folder and its subfolders
  2. Give unique names to files (think of multiple README.md files)
  3. Modify image links in Markdown files to correspond to the Jekyll target folder structure
  4. Copy image files into Jekyll target folder
  5. Build the Jekyll website

Let us consider each Gulp task in turn. Assume the project folder, which includes both code and documentation files is in the path

 

Extract Markdown Files and Give Unique Names

We give to files unique names in the Jekyll format for posts:

By concatenating the date to the folder and file name:

This is performed with gulp-rename

And then write them to a temporary folder:

Copy Image Files into Jekyll

For simplicity, we consider here just JPEG files. The generalization to all types of image files is straightforward.

Images are written into Jekyll under the images folder in a the same folder structure as in the source src folder.

Generate Links To Images In Jekyll Format

We modify images links from the Markdown link structure of, say:

into the Jekyll link structure of:

This is performed with gulp-replace

We then copy the files from the temporary folder into the _posts folder of Jekyll:

Build and Server Jekyll

We use gulp-shell to execute Jekyll build and serve commands:

The Whole Gamut

Get  a Free-Forever Backand Account.