Support custom root URL path as config parameter #26

jrk opened this Issue May 1, 2009 · 9 comments


None yet
6 participants

jrk commented May 1, 2009

Jekyll appears fairly hard-wired to assume that the generated site will live at the root of the web host (post.url, the WEBrick preview server, etc. assume everything begins directly at "/"). It would be useful in many situations to have a Jekyll-generated site living in a specific subdirectory, without requiring lots of template wrangling, and while still supporting the WEBrick preview server. Ideally this would be a single config variable which would:

  • Prefix all system-generated URLs
  • Be available as a Liquid tag for templating
  • Be simulated in the WEBrick preview server

qrush commented May 1, 2009

You can set the destination or source where files are generated:

Also, with the new Permalink system you can pretty much tell your posts to live where you want:

Keep explaining if I'm missing your point here :)

jrk commented May 1, 2009

source, destination, and the new permalink spec all define the structure relative to the local filesystem. They say nothing about where these files will live on the server relative to its URL (not filesystem) root.

For example, with the site exported as http://some.server/url/root/<jekyll-starts-here>, a user would have to hard-code /url/root before CSS files and all other content in the generated _site (or, yes, wherever destination points) in every single template file.

This is doubly problematic:

  • Hard-coding the root URL path directly in all the template source is needlessly inflexible (though admittedly it can be altered with a simple find/replace)
  • It breaks the WEBRick preview server (--server), which is essential for easily previewing the site with links (especially to CSS) intact without having to push to the live server. One of the key reasons this exists, I believe, is to allow quick hosting where Jekyll files reside at the URL root of the server (vs. previewing on an existing site, like personal web sharing on today's desktop OSes, where it would generally have to live in a sub-path, breaking all the absolute links), and for exactly the same reasons, a site which is built (with absolute paths) to live in a sub-path of the URL root will fail during preview (no CSS, internal links break, etc.)

Though it is possible to work around this, above all, it makes it substantially less than obvious to new users exactly how they should set up Jekyll in situations like this. These situations are extremely common, for example, in university or departmental web hosting, and I expect this could be a key demographic for Jekyll use.

There are two obvious solutions that spring to mind:

  • Using relative paths for everything. This could be significantly aided by the template system via a dynamic variable page.relative_path_to_root which would yield something of the form "../../../". This is more complex in the sense that this variable is dynamic per-page, and it does not work with simple existing template examples which link directly to pages and posts via url template variables—specifically, it requires many more changes to the template.
  • Configurable absolute path root. This would be a single static variable site.url_root or similar, specified in _config.yml, used in the templates to configurably define absolute paths to resources (e.g. "{{site.url_root}}/css/screen.css"), and which would cause the WEBrick preview server to host files at http://localhost:4000/url/root/ instead of http://localhost:4000/.

WordPress and its ilk all generally have a core configuration variable specifying where they are exported in the external URL structure, entirely independent of where they live on the filesystem (and never assuming that they are exported at http://host/). I'd like to see essentially the same thing in Jekyll.

jrk commented May 1, 2009

I'm working on a patch to add a url_root config option (which defaults to /) which is exported in the site object, prefixes post URLs in the templates, and which sets the preview WEBrick server to export the site at http://localhost:<server_port>/<url_root> (with a redirect on / to /<url_root> if url_root != '/'). I'll wrap and post it after a string of meetings, but am curious if anyone has thoughts on a better way to handle this general usage model of non-server-root Jekyll site deployments, in case I'm completely crazy.


vilcans commented May 1, 2009

I made a patch that can be used for this (and more):

jrk commented May 1, 2009

Yeah, I saw that, but thanks for the heads-up. It's a very good (and general/powerful) idea. I hope to use it in general. It does not, however, solve the problem of simplifying the templates by making URL generation smarter for posts, or allowing local preview in WEBrick before posting to the live site. I definitely want to see your post hit the mainline, but I've pulled together a more complete solution to the url_root problem which I'll share shortly.


vilcans commented May 1, 2009

That's cool. If you generate relative paths it will be possible to browse the generated site files directly even without WEBrick. That would be nice.

jrk commented Jan 7, 2010

This basic idea is handled nicely by the custom _config.yml => {{ site.* }} mapping added in 0.5.2. The most practical solution, now, is probably allowing dynamic overloading of arbitrary custom config variables, beyond the standard set, via arguments to the Jekyll executable. This would allow running jekyll --server with url_root overloaded to / at preview time, while still leaving the _config.yml value set as necessary for deployment.

I do believe this should be closed, as the method mentioned above solves the problem quite well.

It's worthwhile noting that you may wish to ignore any further changes to your _config.yml with git update-index --assume-unchanged _config.yml.


mojombo commented Jun 22, 2010

Closing this. I'll think about a way to do arbitrary overriding of config settings from the command line.

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017

This issue was closed.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.