Guide to Working with Drafts in Jekyll

tl;dr: To view a Jekyll draft in your browser:

• create a file in the _drafts folder
• add the current date to the front matter, “date: 2019-01-31”
• run $ jekyll serve --drafts
• goto: http://localhost:4000/2019/01/31 to see the draft the same name.
• ???
• profit, err, publish!

source

Introduction

My _posts folder in this Jekyll blog was getting full of drafts. Articles I started but then decided to write on a different topic all together. An unintended consequence is the _posts folder, has actual posts with draft posts.

I wanted to clean it up but also start using the drafts feature of Jekyll. I want to start writing in the _drafts folder, and move publishing articles into _posts.

So, how do I use the _drafts folder???

Consulting the Jekyll documentation on drafts told me to start the server with --drafts option:

$ jekyll serve --drafts

Technically, this worked, but I couldn’t see the drafts locally on the browser. Viewing drafts wasn’t as simple as the documentation made it to be and I had to dig around a bit more. I am sharing my discoveries in working with drafts in Jekyll.

Requirements

This article targets Jekyll blog users. If you do not have a Jekyll blog, please start with this article to start a Jekyll blog, running Jekyll in a Vagrant box, or skip onto one of my articles where I learned about UNIX shell commands.

Pointers to Interesting Parts

I know there are different parts that are interesting to you, so here are useful links to get around this article.

If you want to learn how to create and view drafts going, goto the next section.

If you know that and want to learn about neat magic around drafts, like setting the date published, jump to the magic section.

If you want to know how to set the configuration file to always serve drafts, the configuration section is where you want to go.

If you want to know how to find a file in a crazy folder structure that Jekyll uses, check out the finding drafts section.

Creating Drafts

Let’s create a file in the _drafts folder with the following contents if you want to follow along:

---
layout: post
title: ""
date: 2019-01-01
---

Here’s a oneliner bash command to do the above, run this within the _drafts folder:

$ echo -e "---\nlayout: post\ntitle: 'date in front matter'\ndate: 2019-01-01\n---" > date-in-front-matter.md

(Ever wonder what the -e option does echo? contact me if you can’t find an explanation!)

Serving Drafts

To have Jekyll server to serve items in the _drafts folder locally, run:

$ jekyll serve --drafts

This is in the Jekyll documentation.

Viewing Drafts

With the --drafts parameter, Jekyll server is serving drafts, I open my browser to http://localhost:4000/ but only see the last post from the _posts folder. Where are the drafts???

With my theme, I did not see them at all. The front page of my site showed the most recent entry from the _posts folder, which doesn’t follow the documentation.

So the only way I found them was to use find search through the _site folder used by Jekyll serve. (The find command I used is here)

If you created a draft earlier, the way to view it in the browser would be at this URL:

http://localhost:4000/2019/01/01

The browser will show:

Then you can click to view the draft. That was Easy, right?

Jekyll Draft Magic

With basic understanding of how to view drafts, I will share additional tips I found from digging around the

Draft with Date in Filename

If a draft has the date in the file name, like a regular post, that is the date the server will serve it at:

$ echo -e "---\nlayout: post\ntitle: 'date in filename'\n---" > 2020-01-01-dated-draft.md

Going to http://localhost:4000/2020/01/01/dated-draft will display the draft contents.

Draft with Date in Front Matter

Specifying the date in the front matter without specifying it in the filename will set the date:

$ echo -e "---\nlayout: post\ntitle: 'date in front matter'\ndate: 2021-01-01\n---" > date-in-front-matter.md

Going to: http://localhost:4000/2021/01/01/date-in-front-matter will display the above draft.

Date in filename AND front matter

If you want to get a bit crazy, let’s put conflicting dates in the filename and front matter:

$ echo -e "---\nlayout: post\ntitle: 'date in front matter and filename'\ndate: 2025-01-01\n---" > 2024-01-01-date-in-front-matter-and-filename.md

In this case, the front matter date take precident and the above draft is viewable at:

http://localhost:4000/2025/01/01/date-in-front-matter-and-filename

Neat, right?

No Date anywhere?

In the case where the date is not specified in the filename OR front matter, Jekyll will not just serve the draft as the newest or the current date (which is what I expected…)

It will instead serve the date set in the timestamp! To try this out:

$ echo -e "---\nlayout: post\ntitle: 'timestamped'\n---" > timestamp-draft.md; touch -d 20220101

Going to: http://localhost:4000/2022/01/01/timestamp-draft will display this draft.

Without understanding this, it bewildered me as to why my drafts were showing up in an arbitrary date. This would normally be the current date because well, it’s a draft and the last timestamp should be the current date, right?!

Well, let’s say I have more drafts than I want.

Configuration file

If you do not want to have to type --drafts each time, adding the following entry into _config.yml will enable serving drafts by default:

show_drafts: true

Finding Drafts

Just a handy find command to help find your draft if it isn’t where you think it is.

$ find _site -type f | grep <article name>`

Conclusion

What started as an exercise in sorting out my _posts folder turned into a journey into understanding how Jekyll’s drafts system works with dates and its magic.

If in doubt, include the date within the front matter and manually goto it in format: http://localhost:4000/YYYY/MM/DD where this matches the date from the front matter.

Other forms of using date such as including the date in the filename and in the timestamp also work, it depends on your preference and workflow.

I love that Jekyll has different methods for entering time in drafts and none of them require any configuration.

At the same time, I wish there was a bit more comprehensive documentation on this topic. I got stuck in understanding why I the draft was not appearing in the browser.

Hopefully, this article has helped you understand this topic a bit more.