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

Photo by Kelly Sikkema on Unsplash

Intro

In This Guide

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

Let’s Get Started

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

/
_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

In the Next Part

MOVE TO PART 2

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store