How To Control URLs and Links in Jekyll

Jekyll is a static-site generator that provides some of the benefits of a Content Management System (CMS) while avoiding the performance and security issues introduced by such database-driven sites. It is “blog-aware” with special features to handle date-organized content, although its usefulness is not limited to blogging sites. Jekyll is well-suited for people who need to work off-line, who prefer to use a lightweight editor instead of web forms for maintaining content, and who wish to use version control to track changes to their website.

In this tutorial, we’ll focus on how Jekyll handles URLs and linking since changing URLs will break other people’s link to our pages, as well as links in the content of our own site. URLs are critical to how people find and use websites and warrant consideration before publishing a site for the first time.

We’ll look at how Jekyll creates URLs by default and show how to change the pattern for an individual file or the entire site. Then we’ll look a how to link to pages within our content. Finally, we’ll stage the site for testing.

To follow this tutorial, you will need to complete the previous guides:

• How to Set Up a Jekyll Development Site on Ubuntu 16.04
• Exploring Jekyll’s Default Content

When you’ve completed these, you’re ready to begin.

In Part 2 of this series, we created scaffolding with the jekyll new command and focused on how the resulting site looked in a web browser. Now, let’s take a look at the file structure that was created when Jekyll created the static site.

The _site directory and all the contents beneath it, highlighted below, comprise the static site.

.
├── 404.html
├── about.md
├── assets
│   └── postcard.jpg
├── _config.yml
├── contact.md
├── Gemfile
├── Gemfile.lock
├── index.md
├── _posts
│   └── 2017-09-04-welcome-to-jekyll.markdown
└── _site
    ├── 404.html
    ├── about
    │   └── index.html
    ├── assets
    │   ├── main.css
    │   └── postcard.jpg
    ├── contact.html
    ├── feed.xml
    ├── index.html
    └── jekyll
        └── update
            └── 2017
                └── 09
                    └── 04
                        └── welcome-to-jekyll.html

Unlike database-driven websites, URLs for a static website are literal representations of the directory structure on disk. Jekyll transformed the post’s categories into directories and exploded the date into the file structure, a pattern which is common for many blogs, so that the final URL pattern for this post is /category1/category2/YYYY/MM/DD/words-in-title.html, so the literal URL is http://203.0.113.0:4000/jekyll/update/2017/09/04/welcome-to-jekyll.html.

The scaffolding does not provide dynamic index pages for these directories, so one of two things will happen if a user deletes part of the URL to try to find all the posts from a particular category, year, month or day. If automatic directory indexing is allowed by the web server, they’ll see file and directory information:

In the second case, if the administrator of the production site disabled the directory listings on the server, a user would be denied access:

The category and date-based structure is a common pattern for blog URLS, but how you decide to structure your URLs will depend on the needs of your particular site.

If you want to change the default, Jekyll makes it fairly straightforward to construct URLs. It’s useful to give this some thought before publishing the site for the first time, since changes to the URL patterns impacts how effectively people can find the content with search engines and affects links that others make to the site.

Jekyll’s system for creating URLs is both flexible and powerful. They can be influenced by where and how you name and store the source files, as well as dynamically overridden with a specific value or more general pattern.

title:  "Welcome to Jekyll!"
date:   2017-09-04 03:36:31 +0000
categories: jekyll update

nano ~/www/_config.yml

. . .
permalink: /:categories/:title/

jekyll serve --host=203.0.113.0

├── about.md
├── assets
│   └── postcard.jpg
├── _config.yml
├── contact.md
├── css
│   └── main.scss
├── feed.xml
├── Gemfile
├── Gemfile.lock
├── index.html
├── _posts
│   ├── 2017-09-04-welcome-to-jekyll.markdown
│   └── 2017-09-04-link-test.md
└── _site
    ├── about
    │   └── index.html
    ├── assets
    │   └── postcard.jpg
    ├── contact # originally `contact.html`
    │   └── index.html
    ├── css
    │   └── main.css
    ├── feed.xml
    ├── Gemfile
    ├── Gemfile.lock
    └── index.html
    └── jekyll
        └── update
            └── welcome-to-jekyll
                └── index.html

Now that we know how to control the address where a page is located, there are few things to consider when linking to those addresses.

If we were making links in the body of a page for a completely static site, we would use the URL of the page to which we wanted to link in one of a few formats.

• An absolute link: [Link Text]([http://203.0.113.0:4000/post-name) This is the right format for an off-site link, but inappropriate for our site since keeping the port number on the base URL would break our links in production and omitting it would break them on our development site.
• A root-relative link: [Link Text(/[post-name) Root-relative links only work for local links, and they follow the directory structure on the server starting from the web root because of the initial slash, /.
• A relative link: [Link Text](post-name) The relative link is also for local links and starts following the path from the same directory as the page that contains the link.

Both of the relative links have a similar problem. If we change our link format, we’d need to find all the links to the old URL in our content and update them. Jekyll’s Liquid templating provides a way to link to the posts that’s more flexible. Instead of using a literal link you can use the post_url variable with the name of the file so that instead of linking like this:

[Link Text](/jekyll/update/2016/09/08/welcome-to-jekyll.html)

we would link like this:

[Link Text]({% post_url 2010-09-08-welcome-to-jekyll %})

We only need to include the filename, and there’s no need to include the _posts directory or the file’s extension. A link to a post made this way will continue to work with any permalink settings you configure.

nano ~/www/_posts/2017-09-04-link-test.md

---
layout: post
date: 2017-09-04 07:00
title: Link Test
---

Welcome to my Jekyll Blog. I’m exploring how Jekyll handles links:
* [An absolute link](http://203.0.113.0:4000/about/)
* [A root relative link](/jekyll/update/welcome-to-jekyll/)
* [A Jekyll post_url link]({% post_url 2017-09-04-link-test %})

Liquid Exception: Could not find post
"broken-name-welcome-to-jekyll" in tag 'post_url'.
Make sure the post exists and the name is correct.
in /home/sammy/www/_posts/2017-09-04-link-test.md
                ERROR: YOUR SITE COULD NOT BE BUILT:
               ------------------------------------

Jekyll’s Deployment methods page covers a variety of ways to move your content to its production location depending on your needs. This includes anything from FTP to sophisticated automated methods. For now, we’re going to set up a staging site on the same machine to illustrate how links behave.

sudo apt-get install nginx

sudo ufw allow http

sudo rsync -av ~/www/_site/ /var/www/html/

Testing after a deployment to a new location helps us ensure that our readers have the experience we intend. Automated link checking can help make this an easy and routine part of the process, but for now, we’re going to look at it by hand.

The new blog post appears on the homepage automatically, ordered with the most recent at the top.

When we visit the “Link Test” post, we’ll see that both the absolute link and the root-relative link both break because the environment we deployed to doesn’t use port 4000, while the Jekyll post_url link works in both locations.

We’re done testing, so we’ll shut down nginx and close port 80 since we don’t intend to serve the site:

sudo systemctl stop nginx
sudo ufw delete allow http

We’ve finished our exploration of links and URLs, so we’ll exit the development server with CTRL+C as well.

If we combine carefully chosen, stable page names with linking to posts using the post_url tag, we shouldn’t have too much to worry about when linking to our own pages. Testing in a new location before deploying to production is still valuable for finding our own mistakes, and even more so for finding broken links to external sites.

##Conclusion In this series, we’ve installed and configured a development site. In this tutorial, we looked at how to control the web address of the pages and posts on our site, override the default patterns, create robust links to posts within our content, and deploy the site for testing. You might be interested in learning about customizing your site’s templates and theme or how to deploy your site to its production location.