How to deploy a jekyll site locally with css, js and background images included?

If you can live with having to generate your site for a specific folder, using the html <base /> tag may be more straightforward. With all asset paths relative to your root folder, add the following to your default layout:

<base href="{{ site.baseurl }}" />

Then use the jekyll --base-url <folder> <folder> to deploy your jekyll site to <folder> with the baseurl set up correctly.

Note that this also works without changes with the built-in WEBrick server. Start with jekyll --server and do not specify a custom --base-url.

Update: as gimpf points out in the comment, this will not work as expected with anchor links. Those will point to the base URL instead of the current page. There are workarounds using JavaScript, e.g. rewrite anchor hrefs with jQuery:

$().ready(function() {
  $("a[href^='\#']").each(function(){
    this.href=location.href.split("#")[0]+'#'+this.href.substr(this.href.indexOf('#')+1);
  });
});

Automatic way:

for css/js file:

{% assign lvl = page.url | append:'X' | split:'/' | size %}
{% capture relative %}{% for i in (3..lvl) %}../{% endfor %}{% endcapture %}

<link href="{{ relative }}css/main.css" rel="stylesheet" />
<script src="{{ relative }}scripts/jquery.js"></script>

for other files:

in _config.yml set

url: http://www.yourdomain.com

add canonical link element:

<link rel="canonical" href="{{ site.url }}{{ page.url }}" />

in one of your js file, add:

var relative = null;
if (location.protocol==='file:') {
    relative = Array($('link[rel="canonical"]').attr('href').match(/\//g).length-2).join('../');
    if (relative == '') relative = './';
}
function to_relative(link, index) {
    if (!relative) return link;
    var hash = link ? link.match(/#.*$/) : null;
    if (hash) link = link.replace(/#.*$/, '');
    return link?(link.replace(/^\//, relative)+(index?(link.substr(-1)=='/'?'index.html':''):'')+(hash?hash[0]:'')):null;
}

$(function(){
    if (relative) {
        $('a').attr('href', function(a,b){return to_relative(b, true);});
        $('img').attr('src', function(a,b){return to_relative(b, false);});
    }
});

for other aspects, use jQuery to manipulate them.

The problem is that you are using absolute paths to get to some of your resources. If you want to deploy the site anywhere in the network, then you need to make those relative.

In my case, what I do is to define an (optional) setting called root in the pages/posts that need it, pointing to the "relative root" of the project. For example, on a page located in about/index.html, the root will be ../, since there is only one level "up":

---
title: My Page title
root: "../"
---

Pages further away in the directories will need more dots: ../../, ../../../, and so on. Pages in the root folder (like index.html) don't need a root.

Then I use that setting to generate all the paths.

If I'm on the page or post itself, and I need to refer to a local image or another page, use page.root or post.root:

<img src="{{ post.root }}images/happy.png" />
<a href="{{ post.root }}2010/01/01/another_post>Relative link to another post</a>

It's possible to make the reference directly (../images/happy.png) but this works better when you are creating the site, and you are still unsure about the definitive paths of each page.

I have all the css and js included in one partial file inside _includes. It creates a variable called root to make sure it works with both pages and posts:

{% capture root %}{% if page.root %}{{ page.root }}{% else %}{{ post.root }}{% endif %}{%endcapture%}

<script type="text/javascript" src="{{ root }}js/jquery-min.js"></script>
<link rel="stylesheet" type="text/css" href="{{ root }}/css/style.css" />

That's pretty much it.