How do I reference the root directory of my site? And why won't Jekyll render some pages?

Question

I have a fairly complex javascript project that I've been working on locally up until recently. Its destined for deployment on my github-pages site as a project page.

The problem is, several locations in code, the url starts at the root directory (eg, /js/script.js ). This is kind of necessary, since these files are scattered across sub directories, and I don't want to try and think about ".."-ing my way up a directory tree. This method works perfectly fine locally. But once it gets pushed to github, everything breaks, due to the intervening project name in the url, pushing the root directory one step away from where I want to get files.

I tried what was outlined in this answer, pertaining to using Jekyll's templating features and site.baseurl , but for some reason, Jekyll refuses to actually replace those templates! The urls are all messed up with the {{ site.baseurl }} just sitting in the url, with escape characters and everything. And I refuse to install ruby just so I can try running this thing locally with it, just to debug github's own mess; I have no desire to use Jekyll beyond solving this problem if I can help it.

To complicate matters, I actually have two repos this same code is going into; since this project is rather complex, I have a "Test" version of the repo (seeing as only the "gh-pages" branch ends up remotely accessible as a page on github.io, the solution was to make two repos and push from one to the other). So statically defining baseurl is distasteful anyway, but if it makes the thing work , I'll live with it.

What am I doing wrong??

Answer 1

(It took me several hours of head banging to solve this, which is why I figured I would submit this pre-answered question, to help others that have similar aspects of my problem.)

Let's take the answer in small, independently usable chunks:

Why Jekyll refuses to replace the templates everyone keeps suggesting

Though several places tell you about the wonders of the Liquid Templating system's {{ output }} and {% tags %} , very few places tell you that in order for Jekyll to actually process these templates, the files must contain Front Matter . That is, the file you wish to process must begin with the following, at the least:

---
---

Yes, three dashes, on two separate lines. No, you may not condense them to one line. This is required for every file you want Jekyll to actually process the template syntax for, instead of just copying as is.

How you can access your project's path on github-pages dynamically

As I mentioned above, I have two different repositories that the same code was going to end up in, so if I could avoid hard-coding the name of my project, it would be lovely.

Fortunately, github provides a non-standard jekyll site variable in the form of site.github , which is a treasure trove of various repository metadata and hidden information about how github-pages operates.

And fortunately one of the many metadata properties is site.github.project_title , which gives you the title of the project, which coincidentally is the path the pages will be running under. Surely I can just assign that to site.baseurl , and all will be well.

How Jekyll is not as flexible as it makes itself out to be

Sadly not. The _config.yml file is actually quite rigid: you may not reference other variables from here, it is only for static text and object definitions. The same, to my dismay, also goes for the Front Matter that you must have at the top of each file to process.

The format the templating system uses is also rather unconventional: There are no traditional operators. You cannot assign with "=", nor can you concatenate strings with "+" or "." or any other character. To assign to a variable a concatenated string of literals and variables, you need to use a "capture tag".

So how do I get the contents of the very convenient variable github provides into my urls? Well, I can use the following:

{% capture baseurl %}{{ site.github.project_title | prepend:'/' }}{% endcapture %}

This conglomeration of tags and output prepends a slash onto the previously mentioned project title, and then assigns that to a variable called "baseurl". (It might also be possible to simply put a slash before the output, but this is what I went with.) No, this variable is not the same as "site.baseurl". This variable is available only on the page this line is run on, and is referenced with the output {{ baseurl }} . Thus:

<script src="{{ baseurl }}/js/jquery-2.1.1.min.js"></script>

Thus at the top of every one of my html files, I have the following:

---
---
{% capture baseurl %}{{ site.github.project_title | prepend:'/' }}{% endcapture %}

(And then in the head tag, because I don't want to have to put it also at the top of my js files, I have <script>window.BASEURL = "{{ baseurl }}";</script> )

Fortunately for me, I have a build process already setup (involving browserify) so I have simply added these lines to the start of any .html files via a build step. Those without such a thing will have to remember to manually add it.

How this may screw over those who actually use jekyll

I don't use Jekyll, and I simply wanted my program to work on github-pages. My aforementioned build process takes another step after it is finished to shallowly replicate Jekyll insomuch as it strips out all the templating syntax, so I can test it locally. Those who use Jekyll to test locally may find that setting site.github.project_title as a command-line argument or in the _config.yml will result in paths that have an extraneous slash in them.

I hope this helps someone save a couple hours, at least in trying to figure out why jekyll won't process templates, if not the other sections.