Build a Ready-To-Use Jekyll Setup — Part 1: New Project

4 min readOct 25, 2022

Intro

Jekyll is known for its ability to build simple static websites and blogs from text files and templates. However, when creating more complex websites, i.e. websites in two different languages or when trying to build the navigation bar dynamically, things can become more tricky. While many tutorials on these and other Jekyll related topics exist, they only cover single issue in isolation or aren’t detailed enough to provide you with a production-ready solution.

In This Guide

We will develop a ready-to-use Jekyll setup from scratch. The final setup can be used as a base to develop multi-page websites with static content that is served in two different languages from an Apache HTTP server.

A GitHub repository is linked at the end of each article in case you are only interested in single parts of this guide.

What You Will Learn

How to

generate a navigation menu dynamically according to a predefined structure
build a multi-page website in two different languages
configure a virtual host of an Apache HTTP Server in order to serve your website depending on the browser’s language

Prerequisites

Ruby version 3.0.0 or higher, as well as Jekyll (we use version 4.2.2 in this guide) and bundler gems installed on your machine (Jekyll installation guide)
Apache HTTP server 2.4
Basic knowledge on how Jekyll works and how to use partials, layouts, CSS/SCSS ,and JavaScript within Jekyll

In This Part

We will setup a new Jekyll project and prepare it for the upcoming parts. At the end of this part, it will contain two pages, as well as entry points for CSS and JavaScript.

Let’s Get Started

Open your terminal at the desired working directory (project root folder) and create a new Gemfile with

bundle init

and add the Jekyll and webrick gems to the Gemfile:

bundle add jekyll webrick

Next create the following files and folders in the project root directory:

_config.yml:

For now we only specify the Sass directory in the configuration file, but we will add additional parameters later.

index.html (Use Markdown files alternatively):

legal.html:

The two HTML files index.html and legal.html contain the main content of the two HTML pages. The content will be included in the layout as specified in the front matter.

Now create the following required directories:

_includes
_layouts
_sass
css
js

The _includes/ directory will host reusable HTML templates, such as header and footer sections. These so called partials are then used to compose the HTML pages. Therefore, in _includes/ create the following partials:

head.html:

header.html:

footer.html:

nav.html:

scripts.html:

The head.html contains all elements for the <head> section of a HTML page, such as a link to the stylesheet. header.html and footer.html contain the content for the <header> and <footer> elements of the HTML page. Further, nav.html serves as a very basic navigation menu and contains links to the two pages which we created before. The scripts.html contains the links to the JavaScript file.

We compose our website layout with these partials by creating a default.html layout file in the _layouts/ directory with the following content:

During the build process, Jekyll replaces each placeholder with the content of the respective partial.

Next, we implement a basic styling. Similar to the HTML partials, the styling can be split into multiple Sass files. However, in this guide, we will put all styling into a single file. Therefore, create a new file base.scss in the _sass/ directory with the following content:

In the css/ directory create main.scss with the following content:

This file serves as the entry point for the website’s styling where we import the Sass files from the _sass/ directory. If you intend to split you CSS/Sass into multiple files, you have to create the additional Sass files in the _sass/ directory and then import them in main.scss. It is imported to add empty front matter at the top of the entry file. Otherwise, Jekyll does not process it during build. Note that the base.scss file is imported without stating the complete path. That is possible because Jekyll knows where to look up for Sass files, since we defined the Sass directory in the configuration file _config.yaml.

We also want JavaScript to be integrated in our setup. Therefore, create a main.js file in the js/ directory with the following content:

We only log a message to the browser’s console after the page has been loaded to ensure that JavaScript is properly referenced.

Result

We now have the following folder structure:

/
 _includes/
   footer.html
   head.html
   header.html
   nav.html
   scripts.html
 _layouts/
   default.html
 _sass/
   base.scss
 css/
   main.scss
 js/
   main.js
 _config.yml
 Gemfile
 Gemfile.lock
 index.html
 legal.html

Running bundle exec jekyll serve in your terminal now builds and serves the website under http://127.0.0.1:4000.

Illustration of the result — Illustration: Result of part 1

In this basic configuration we have a website with two pages and a basic styling. If you open your browser’s console and refresh the page, you will see the message Page loaded., which ensures that JavaScript is loaded properly.

Source Code

GitHub: Jekyll Setup - Part 1

In the Next Part

We are going to make our website bilingual in the next Part.

MOVE TO PART 2