Best Steps to Install and Configure Jekyll on Debian 11

By Posted on

Best Steps to Install and Configure Jekyll on Debian 11

Best Steps to Install and Configure Jekyll on Debian 11

This guide aims to walk you through the process to Install and Configure Jekyll on Debian 11. Jekyll is a powerful tool that allows you to "generate" or create static websites. In essence, it’s a static site generator. But what does that mean?

Jekyll excels at managing website templates – the consistent elements like navigation menus, headers, and footers that appear across your site. Instead of manually coding these elements into every single webpage, which is tedious and time-consuming, Jekyll allows you to define them once. It then combines these templates with individual content files (such as blog posts) to produce complete, ready-to-serve HTML pages.

The beauty of Jekyll lies in its efficiency. It doesn’t require dynamic content generation on the fly, which is very different from platforms that query a database and construct a page each time a user visits. Jekyll pre-builds all your site’s HTML pages, only updating them when the underlying content changes. This results in incredibly fast loading times and reduced server load.

Follow the steps outlined below to Install and Configure Jekyll on Debian 11. This guide is brought to you by Orcacore.

Before we begin, ensure you’re logged into your Debian 11 server as a non-root user with sudo privileges and that you have a basic firewall configured. If you haven’t already done this, refer to our guide on Initial Server Setup with Debian 11 for detailed instructions.

Let’s begin to Install and Configure Jekyll on Debian 11.

Step 1 – Install Ruby on Debian 11

Jekyll is built using the Ruby programming language, making Ruby a prerequisite for running Jekyll on your Debian server.

First, update your system’s package list to ensure you’re installing the latest versions of packages:

sudo apt update

Next, install Ruby and the necessary build tools and development libraries:

sudo apt install make build-essential ruby ruby-dev

Verify that Ruby is installed correctly by checking its version:

ruby -v

You should see an output similar to:

**Output**
ruby 2.7.4p191 (2021-07-07 revision a21a3b7d23) [x86_64-linux-gnu]

Step 2 – Set up Jekyll on Debian 11

With Ruby installed, the next step is to configure the Ruby Gems environment and then proceed to Install and Configure Jekyll on Debian 11.

Configure Ruby Gems Path

The Ruby Gems package manager needs to be configured to install gems (Ruby libraries) in a user-specific directory. This prevents permission issues and keeps your system clean.

Open your .bashrc file using your preferred text editor. Here, we’re using vi:

sudo vi ~/.bashrc

Add the following lines to the end of the file:

# Install Ruby Gems to ~/.gems
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH

Save the changes and close the file.

To apply these changes to your current shell session, source the .bashrc file:

sudo source ~/.bashrc

Install Jekyll Site Generator on Debian 11

Now, you can use the gem command to install Jekyll and Bundler:

gem install jekyll bundler

This command will download and install Jekyll and Bundler along with their dependencies. You should see an output similar to:

**Output**
Successfully installed bundler-2.4.8
Parsing documentation for bundler-2.4.8
Installing ri documentation for bundler-2.4.8
Done installing documentation for bundler after 0 seconds
29 gems installed

Configure Firewall for Jekyll

Jekyll, by default, runs on port 4000. To access your Jekyll site from outside your server, you need to open this port in your firewall.

If you’re using ufw (Uncomplicated Firewall), use the following command to allow traffic on port 4000:

sudo ufw allow 4000

Reload the firewall to activate the new rule:

sudo ufw reload

Step 3 – Create a New Demo Site with Jekyll

Now that you have successfully Install and Configure Jekyll on Debian 11, let’s create a sample site to verify that everything is working correctly.

Navigate to your home directory and use the jekyll new command to create a new Jekyll project:

# cd ~
# jekyll new demo-site

This command will create a directory named demo-site containing a basic Jekyll site structure.

You can inspect the files within the demo-site directory using the tree command. If you don’t have tree installed, you can install it with:

# sudo apt install tree
# tree demo-site

You will see a file structure similar to the following:

**Output**
demo-site
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
└── _posts
    └── 2023-03-09-welcome-to-jekyll.markdown

1 directory, 7 files

Run Web Server with Jekyll

Jekyll can monitor the files in the created directory and quickly generate a static site from them on Debian 11. It also automatically regenerates the site when changes are made to these files.

To start the Jekyll development server, navigate to the demo-site directory and run the jekyll serve command:

# cd ~/demo-site
# bundle add webrick
# jekyll serve --host=<your-host-ip-address>

Note: If you don’t specify a host, Jekyll will serve the site on localhost. Replace <your-host-ip-address> with the actual IP address of your server if you want to access it from other machines.

The output should look something like this:

**Output**
Auto-regeneration: enabled for '/root/demo-site'
    Server address: http://ip-address:4000/
  Server running... press ctrl-c to stop.

Jekyll will now watch for changes in your demo-site directory and automatically rebuild the site whenever a file is modified. The generated site is located in the _site directory.

tree ~/demo-site
**Output**
/root/demo-site
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
├── _posts
│   └── 2023-03-09-welcome-to-jekyll.markdown
└── _site
    ├── 404.html
    ├── about
    │   └── index.html
    ├── assets
    │   ├── main.css
    │   ├── main.css.map
    │   └── minima-social-icons.svg
    ├── feed.xml
    ├── index.html
    └── jekyll
        └── update
            └── 2023
                └── 03
                    └── 09
                        └── welcome-to-jekyll.html

9 directories, 15 files

To run the Jekyll server in the background:

jekyll serve --host=<host-ip> > /dev/null 2>&1 &

Access Jekyll Site on Debian 11

Now that you’ve successfully Install and Configure Jekyll on Debian 11 and started the server, you can access your new Jekyll site by opening a web browser and navigating to:

http://<IP_Address>:4000

Replace <IP_Address> with the actual IP address of your Debian server.

You should see the default Jekyll welcome page.

[Image of Jekyll welcome page site]

Now, let’s add a new post to your Jekyll site.

Create a Sample Post on Jekyll

Jekyll posts are stored in the _posts directory. The filenames must follow a specific naming convention:

YEAR-MONTH-DAY-title.MARKUP

Where:

  • YEAR is the four-digit year.
  • MONTH is the two-digit month.
  • DAY is the two-digit day.
  • title is the title of the post (using hyphens instead of spaces).
  • MARKUP is the file extension (e.g., md for Markdown or html for HTML).

For example, to create a "Hello World" post, use the following command:

vi ~/demo-site/_posts/2023-01-07-hello-world-blog.md

Add the following content to the file:

---
layout: post
title:  "Hello World!"
---

# Welcome

**Hello world**, this is my first Jekyll blog post.

I hope you like it!@OrcaCoreTeam

Save the file and close the editor.

Refresh your Jekyll site page, and you will see:

[Image of Add a Jekyll Post]

Clicking on your post will display its content:

[Image of Jekyll Post content]

For further information and advanced usage, consult the official Jekyll documentation.

Conclusion

You have now learned how to Install and Configure Jekyll on Debian 11. Jekyll simplifies the creation of static websites. As demonstrated in this guide, the installation and configuration process is relatively straightforward.

We hope you enjoy using Jekyll!

You might also find these articles helpful:

  • Enable Kernel Crash Dump on Debian 11
  • Installing PHP 8.3 on Debian 11
  • Find Which Process Listening on a Port on Debian 11
  • Upgrade Linux Kernel on Debian 11

Alternative Solutions for Static Site Generation on Debian 11

While Jekyll is a popular choice for static site generation, other excellent options are available on Debian 11. Here are two alternative approaches, along with code examples, to achieve similar results.

1. Hugo:

Hugo is a fast and flexible static site generator written in Go. Known for its speed and simplicity, Hugo is an excellent choice for large websites with numerous pages.

Installation:

First, download the appropriate Hugo binary from the official releases page for your architecture and Debian version. You can also install it through snap:

sudo snap install hugo

Creating a new site:

hugo new site quickstart
cd quickstart

Adding a theme:

Hugo utilizes themes for styling and layout. Choose a theme from the Hugo Themes directory and add it to your project.

git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> hugo.toml

Creating content:

hugo new posts/my-first-post.md

This creates a new markdown file in the content/posts directory. Edit the file with your desired content. Here is an example:

---
title: "My First Post"
date: 2023-10-27T10:00:00-05:00
draft: false
---

Welcome to my first Hugo post! This is a test.

Running the server:

hugo server -D

Hugo’s built-in server will start, and you can access your site at http://localhost:1313. The -D flag includes draft posts.

2. Eleventy (11ty):

Eleventy, also known as 11ty, is a simpler static site generator written in JavaScript. It’s praised for its flexibility and ease of use, allowing you to use various templating languages like Markdown, HTML, Liquid, Nunjucks, and JavaScript.

Installation:

First, you’ll need Node.js and npm (Node Package Manager) installed.

sudo apt update
sudo apt install nodejs npm

Then, install Eleventy globally:

npm install -g @11ty/eleventy

Creating a project:

Create a new directory for your Eleventy project:

mkdir my-eleventy-site
cd my-eleventy-site
npm init -y

Creating a basic template (index.html):

Create an index.html file with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Eleventy Site</title>
</head>
<body>
    <h1>Hello, Eleventy!</h1>
    <p>This is a simple Eleventy site.</p>
</body>
</html>

Running Eleventy:

Run the Eleventy build command:

npx @11ty/eleventy

This will generate a _site directory containing your static website.

Serving the site:

You can use a simple HTTP server to serve the generated site. One option is npx serve:

npx serve _site

This will start a server, and you can access your site at the address displayed in the terminal (usually http://localhost:5000).

Both Hugo and Eleventy offer compelling alternatives to Jekyll, providing different strengths and catering to diverse preferences. Choosing the right tool depends on your project’s specific requirements, your familiarity with the underlying technologies, and your desired level of customization.

Related posts: