Use Jekyll without Jekyll server / without root directory

Question

I just started using Jekyll today, and I'm trying to figure out how to use it to create a portable static site. Specifically, I want to be able to access the site without using the Jekyll server.

This answer says that this isn't possible, however, it's a couple years old, and it seems like a static site generator should be able generate a site which doesn't need a server to function (can be accessed through the browser as a file file:///...)

The Jekyll docs say that a Jekyll site can be deployed on a remote server by placing the _site/ folder in the web server's root directory. How do I force Jekyll to use relative links, so that I can run the built site from a directory other than the root?

I'm worried that the answer to this question is "it's not possible", or at least "it's not possible without some trickery". I've used Wordpress in the past, and it's trivial to set up a wordpress installation in any directory on a LAMP server. I feel like there has to be some easy way to do this with Jekyll, but I can't find the answer anywhere.

David Jacquel David Jacquel · Accepted Answer · 2016-08-05T10:22:15

This answer is still valid. But I must admit that it's not really portable to tweak baseurl. You cannot always guess the correct path.

Let's try to make it run on the file system with relatives urls like ./path/to.

What do we need to tweak

Examining the index page, sitting at file:///path/to/_site/index.html, we can identify some potential problems :

styles are not working
posts are linked like file:///jekyll/update/2016/08/05/welcome-to-jekyll.html following the /:categories/:year/:month/:day/:title.html permalink pattern. And we know the folder hierachy is a nightmare when using relative links.
pages. The only one is about with an already defined permalink pointing to /about/ which will not work from file system, because it resolves to file:///about/

In order to avoid folder hierachy hell, we will make every post and page to be created at the root.

Redefining permalinks

In _config.yml we add :

defaults:
  -
    scope:
      type: "posts"
    values:
      permalink: :slug:output_ext

  -
    scope:
      type: "pages"
    values:
      permalink: :basename:output_ext

Now any post is generated at the root.

But this about page is still generated in an about folder. Why ?

Because front matter permalink overrides default configuration. We remove permalink: /about/ from about.md front matter and now our page is generated at the root /path/to/_site/about.html. Good !

Rewriting links

We're now making our links relatives to root using the ./ expression.

_includes/head.html

<link rel="stylesheet" href="{{ "/css/main.css" | prepend: site.baseurl }}">

becomes

<link rel="stylesheet" href="{{ "./main.css" }}">

_includes/header.html

<a class="site-title" href="{{ site.baseurl }}/">{{ site.title }}</a>

becomes

<a class="site-title" href="./index.html">{{ site.title }}</a>

And

<a class="page-link" href="{{ my_page.url | prepend: site.baseurl }}">{{ my_page.title }}</a>

becomes

<a class="page-link" href="./{{ my_page.url }}">{{ my_page.title }}</a>

index.html

<a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a>

becomes

<a class="post-link" href="./{{ post.url }}">{{ post.title }}</a>

And you can now navigate.

Remember to keep everything a the root and it will be ok.

Use Jekyll without Jekyll server / without root directory

2 Answers

What do we need to tweak

Redefining permalinks

Rewriting links