Recently I’ve had Jekyll complaining about post_url not working due to a missing file, but the file was there. This took me some time to figure out and I would like to share the issue (a non-obvious stray whitespace in the filename) as well as other ways this could have happened.

Brief intro

Some of you may not know what Jekyll or post_url is. Let me briefly explain.

Jekyll

Jekyll is a tool for creating static html blogs. Basically you give Jekyll your blog “source code” and Jekyll “compiles” it into nicely looking static html blog, which you can then host somewhere (like GitHub pages). As an example, this blog is done precisely like that - Jekyll + GitHub pages. Can’t I write plain html myself without any fancy “compiling”? I can, but that’s cumbersome. I would have to explicitly care about html when writing my posts and also manually add all the boilerplate to each page. Instead I just write a text of the post (i.e. the most exciting part of the process) using special language called markdown and Jekyll does all the remaining boring stuff for me.

post_url tag

This markdown language has special commands, which one can use to make writing easier. This can be something simple like making text bold or italic or something more complex like creating a table or adding a link somewhere. These commands are called tags. post_url is a tag for adding a link to another post in your blog. Obviously, I could just hardcode a direct link, but post_url has couple advantages:

  • complains if the link is broken
  • changes the link if something changes (e.g. domain name or post url change)
  • allows not to think about what the link will actually be and, thus, saves times.

The problem

I was happily writing a summary for lectures 4-5 of Robert Sapolsky’s course and I wanted to add a link to the summary of lectures 1-3. So I wrote

[1-3 - Intro & Behavioral Evolution]({% post_url 2019-03-17-human_behavioral_biology_sapolsky_course_summary_lectures_1_3  %})

The name of the file I just copied. To my sheer surprise this didn’t work:

Liquid Exception: Could not find post 
"2019-03-17-human_behavioral_biology_sapolsky_course_summary_lectures_1_3"
in tag 'post_url'. Make sure the post exists and the name is correct. 
in /blog/source/_posts/2019-03-26-human_behavioral_biology_sapolsky_course_summary_lectures_4_5.markdown
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    Could not find post "2019-03-17-human_behavioral_biology_sapolsky_course_summary_lectures_1_3" 
                    in tag 'post_url'. Make sure the post exists and the name is correct.

The solution

After googling for some time, I accidentally noticed that the filename of the post I was trying to link to had a space right before the extension:

                                                    this little guy here
                                                                        \
2019-03-17-human_behavioral_biology_sapolsky_course_summary_lectures_1_3 .markdown

When I copied the filename, the space was copied as well, but Jekyll ignored it, because that’s how tags work.

What’s funny is that Jekyll tags handle spaces inside the file name well, e.g. a file named

2019-03-17-human behavioral biology sapolsky course summary lectures_1_3.markdown

works perfectly fine.

Other possible causes

Since I spent time googling this, let’s collect here other possible causes, which could lead to this error:

  • Post is not published. This can happen for multiple reasons, e.g.
    • explicit published: false
    • published date is from the future (including due to timezone)
    • wrong folder (it should be in _posts)
    • the file is missing the date prefix or it is not separated from the rest of the filename with -
  • The post belongs to a collection (use link tag instead)

If this does not solve your problem (or you are curious), you might look at the source code.

Happy error free blogging!