Understanding URL Handling in Jekyll: Filters, Configs, and Best Practices

Understanding URL Handling in Jekyll: Filters, Configs, and Best Practices

In Jekyll, URLs are handled using the url and relative_url filters, and by using variables defined in your _config.yml file. Here’s a quick rundown on how to use URLs in Jekyll:

🔗 1. Basic Site URL Configuration

In your _config.yml, you usually define:

url: "https://example.com"      # your domain name
baseurl: "/blog"                # if your site is in a subdirectory ("" if in root)

🏷️ 2. Using the url Filter

This will convert a relative path into a full URL.

<a href="/about/">About</a>

Output:
https://example.com/blog/about/ (based on the config above)

🏠 2. Site URL (site.url)

This is typically set in your _config.yml file and represents the base URL of your site:

# _config.yml
url: "https://example.com"

Then in your layouts or templates, you might use it like this:

<a href="https://yasirbhutta.github.io/about">About</a>

Or better yet, combine with site.baseurl:

<a href="https://yasirbhutta.github.io/about">About</a>

📄 3. Page/Post URL (page.url)

This gives the relative URL of the current page or post. Example usage:

<!-- Outputs something like: /blog/my-post/ -->
/jekyll/docs/jekyll-url-handling.html

This is useful for canonical links, social shares, or navigation highlighting.

💡 Example Use Case:

<!-- Full link to the current page -->
<link rel="canonical" href="https://yasirbhutta.github.io/jekyll/docs/jekyll-url-handling.html">

🔁 4. Using the relative_url Filter

This is safer for local development (doesn’t include the domain):

<a href="/about/">About</a>

Output:
/blog/about/

🧠 5. Linking to Posts or Pages

You can also use built-in variables:

<a href="/jekyll/docs/jekyll-url-handling.html">Understanding URL Handling in Jekyll: Filters, Configs, and Best Practices</a>

Or for posts:

<a href=""></a>

🛠️ 6. Linking Static Assets

<img src="/assets/images/logo.png" alt="Logo">

✅ Pro Tip:

If you’re working in development (jekyll serve), site.url might be blank unless you set it. So you may want to guard against that in templates:

  <a href="https://yasirbhutta.github.io/jekyll/docs/jekyll-url-handling.html">Permalink</a>