If you’re looking to build a static website or blog quickly, Jekyll could be a great solution. An open-source static-site generator written in Ruby, Jekyll allows for quick execution of commands that help manage your site from initial to production deployment, all from your command line. Jekyll is blog-aware, giving priority to categories, posts, and layouts with a range of importers available to import previous blog content. If you need to work offline often, prefer using lightweight editors to web forms for content maintenance, or wish to use version control to track changes to your website, Jekyll could provide you with what you need to accomplish your goals.
In this tutorial, we will install a Jekyll development site on Ubuntu 18.04 with automatically-generated content. With Jekyll installed, you’ll be able to create a personal site or blog primarily using markdown files and a few Jekyll commands.
To follow this tutorial, you will need:
Once you’ve completed this prerequisite, you’re ready to install Jekyll and its dependencies.
We’ll start by updating our package list to be sure we have the latest information on the newest versions of packages and their dependencies:
- sudo apt update
Next, let’s install make
and build-essential
so that Jekyll’s libraries will compile, and for Ruby and its development libraries to use. We include the y
flag here to confirm that yes, we would like to install the packages and avoid the prompt to confirm.
- sudo apt -y install make build-essential ruby ruby-dev
When that’s complete, let’s add two lines to our .bashrc
file to tell Ruby’s gem
package manager to place gems in our user’s home folder. This avoids problems occurring from system-wide installations while also adding the local jekyll
command to the user’s PATH
.
Open .bashrc
with an editor of your choice, such as nano:
- nano .bashrc
At the bottom of the file, add the following lines:
# Ruby exports
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH
Save and close the file. To activate the exports, run the following:
- source ~/.bashrc
When that’s complete, we’ll use gem
to install Jekyll itself as well as Bundler, which manages gem dependencies. Note that this may take some time.
- gem install jekyll bundler
Next, we’ll make sure that our firewall settings allow traffic to and from Jekyll’s development web server.
Let’s check whether the firewall is enabled. If so, we’ll ensure traffic to our site is permitted so we will be able to view our development site in a web browser.
- sudo ufw status
If you’ve encountered a status showing inactive
, run the following commands.
ufw allow OpenSSH
sudo ufw enable
This will enable your firewall to run on system startup. You may get the following prompts (confirm with ‘y’ to continue):
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup
In our case, only SSH is allowed through:
OutputStatus: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
You may have other rules in place or no firewall rules at all depending on how you have set up your firewall. Since only SSH traffic is permitted in this case, we’ll need to open port 4000, the default port for the Jekyll development server:
- sudo ufw allow 4000
Now our firewall rules should include the following:
OutputTo Action From
-- ------ ----
OpenSSH ALLOW Anywhere
4000 ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
4000 (v6) ALLOW Anywhere (v6)
Now with the software installed and the necessary port open, we’re ready to create the development site.
From our home directory, we’re using Jekyll’s new
command to create scaffolding for a site in a subdirectory called www
:
- cd ~
- jekyll new www
The jekyll new
command initiates a bundle install
to install the required dependencies, then automatically installs a theme called Minima. Following a successful installation, you should receive output like the following:
OutputNew jekyll site installed in /home/sammy/www.
Jekyll’s new
command creates the following directories and files:
...
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
├── _posts
│ └── 2020-05-29-welcome-to-jekyll.markdown
└── _site
These aren’t the actual web site files. They are the source files that Jekyll will use to create the static site. Jekyll relies on specific names, naming patterns, and directory structures to parse the different sources of content and assemble them into a static site. It’s important to use the existing structure and follow Jekyll’s naming conventions when adding new posts and pages.
Tip: tree
is a useful command for inspecting file and directory structures from the command-line. You can install it with the following command:
- sudo apt install tree
To use it, cd
into the directory you want and type tree
or provide the path to the starting point with tree /home/sammy/www
Jekyll’s built-in lightweight web server is tailored to support site development by monitoring the files in the directory and automatically regenerating the static site any time a change is saved.
Because we are working on a remote server, we’ll specify the host address in order to browse the site from our local machine. If you are working on a local machine, you can run jekyll serve
without the host setting and connect with http://localhost:4000
.
- cd ~/www
- jekyll serve --host=203.0.113.0
Output of jekyll serverConfiguration file: /home/sammy/www/_config.yml
Source: /home/sammy/www
Destination: /home/sammy/www/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.645 seconds.
Auto-regeneration: enabled for '/home/sammy/www'
Server address: http://203.0.113.0:4000/
Server running... press ctrl-c to stop.
When we invoked jekyll serve
, Jekyll parsed the configuration and content files into a new directory, _site
and started serving the content in that _site
folder:
...
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
├── _posts
│ └── 2020-05-29-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
└── 2020
└── 05
└── 29
└── welcome-to-jekyll.html
It also started watching the current directory, www
, for changes. As soon as a change to a post or page is saved, the static site will automatically be rebuilt, so it’s important not to make changes directly to files in the _site
folder.
If we leave this terminal open with the development server running in the foreground when working on our site, we’ll receive immediate feedback as we add pages and posts and change content.
Note: If you’re working with a large site, enabling the --incremental
build can speed up the rebuild each time you make a change by only regenerating the files that are changed, but we don’t need it for this small site. You can learn more about this experimental feature on the Jekyll website.
The site is now available. In a web browser, we can visit it at the server address and port shown in the the output from jekyll serve
:
In this tutorial, we installed Jekyll and created a development site with some automatically-generated content. You can learn more about Jekyll by reading our other tutorials on the subject:
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!