Jekyll command to publish a draft #1469

zsiegel · 2013-08-28T23:56:37Z

It would be great to have a command to publish a draft.

For example if you did jekyll publish _draft/path-to-draft.md it would move the file into your _posts folder and date it with the current date.

I would love to help implement the feature but I cannot seem to get jekyll to build on my machine.

When trying to build I get the following error. I might be totally missing something but any nudge in the right direction or quick steps to building and iterating would be great.

(master)$ jekyll build --trace /Users/zsiegel/.rvm/gems/ruby-1.9.3-p194/gems/commander-4.1.5/lib/commander/runner.rb:365:in block in require_program': program version required (Commander::Runner::CommandError)`

Thanks!

The text was updated successfully, but these errors were encountered:

courajs · 2013-08-29T03:57:23Z

I was just thinking the same thing. It does feel to me like a natural extension of the drafts feature.

parkr · 2013-08-29T16:27:01Z

Great idea!

That error is usually due to a Syntax Error. Within your fork, run bundle exec rake console or, if that doesn't work, bundle exec irb -r lib/jekyll.rb and the error should show itself. Commander uses a lot of metaprogramming that swallows this.

parkr · 2013-08-29T16:27:16Z

@benbalter @mattr- what do you think of this?

zsiegel · 2013-08-29T16:41:34Z

@parkr thanks for your help i was able to track down the issues and it seems to be building and running the tests now. Ill try and hack around this weekend and see what I can come up with.

mattr- · 2013-08-29T16:46:12Z

I like it. When could we see some code? 😃

On Thu, Aug 29, 2013 at 11:41 AM, Zac Siegel notifications@github.comwrote:

@parkr https://github.com/parkr thanks for your help i was able to
track down the issues and it seems to be building and running the tests
now. Ill try and hack around this weekend and see what I can come up with.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1469#issuecomment-23504023
.

benbalter · 2013-09-04T22:37:43Z

I've been giving this some thought, and I've actually started to open an issue several times called "deprecate drafts", but haven't gone through with it. I think drafts as a feature encourage the wrong workflow. The command to publish a draft should be git merge feature-branch.

The amazing thing about Jekyll is that it treats content as code. It wraps your code in the same satin blanket that is GIt as geeks do with the software they use to publish that same content, and that makes a heck of a lot of sense. After all, the content is the important part, not the platform.

Geeks care about code, and if so much as a single line is off, things break. That's why we have great tools, and that's why applying that workflow and that philosophy to content is so powerful.

The draft feature breaks that flow. It says hey, even though we have this amazing tooling that allows us to create parallel versions, save them, version them, expose them early on for feedback from others... lets ignore all that and invent our own system to stage content. We don't do that with code, we shouldn't do that with text.

Here's how a draft flow should work if we want to encourage flow:

git checkout -b descriptive-name
touch _posts/YYYY-MM-DD-descriptive-name.md
$EDITOR _posts/YYYY-MM-DD-descriptive-name.md
git add _posts
git commit _posts
[a pull request if working with others]
git checkout master && git merge descriptive-name

That process isn't for everyone, but we can build tooling to fix that. What if jekyll draft foo did step 1-3. What if jekyll publish foo did steps 4-7. What if we encouraged our users to use an established, but significantly more evolved workflow, rather than building our own from scratch.

Caveat: This assumes you're using git, which up until now, Jekyll does not. We'd either want to make that assumption, or have a non-git fallback to the existing workflow.

courajs · 2013-09-04T22:43:26Z

I think that wouldn't enable the 'browse your drafts, and see which you feel like developing a bit more' kind of workflow which it currently encourages. I think that's kind of what it's built around.

mattr- · 2013-09-05T03:49:19Z

@benbalter Great thoughts. Seems so simple now that you mention it. 😃

With Ben's example, you'd have a different feature branch for each draft.
Browsing your drafts becomes a simple git branch. @FellowMD Would that
address your workflow issues?

courajs · 2013-09-05T14:48:23Z

If I had to switch one by one between drafts that would ruin the feature for me. There's something about having them all displayed next to each other that helps you realize which one should see the light of day next.
Like this: http://obtvse.herokuapp.com/admin
(username:username, password:password)

parkr · 2013-09-05T14:56:20Z

Whoa whoa hold your 🐴! We can't assume everyone uses Git (as Ben mentioned) and I'd feel really uncomfortable about integrating git with Jekyll so tightly. It's enforcing a workflow that isn't flexible – what if I work in a different way? I'll submit a PR to modify the workflow or never use this feature.

Integrating git is a can of worms I don't want to open. All we want is an automated way to move a file from _drafts to _posts and to give it that moment's date. Doing anything more is locking us and our users into a certain way of working and this project doesn't seem to be about that at all.

The idea is brilliant and the workflow certainly works for some, but I don't think it's within the domain of Jekyll to enforce this. It's more in the domain of Octopress than Jekyll.

zsiegel · 2013-09-05T15:05:54Z

I kind of agree with Parker. I was thinking about a basic command that would move and date the draft appropriately. Obviously I could do this with shell scripting or other methods on my local machine but I thought it might be a nice extension to the drafts functionality.

Within the git workflow Ben mentioned I could see the following…

git branch my-draft-branch
jekyll publish _drafts/path-to-draft.md
git commit & Push

mattr- · 2013-09-05T15:44:27Z

Nobody ever said we would be integrating Git in to Jekyll or enforcing a workflow. We're just having a discussion about workflows. Let's calm down, shall we? 😃

Do I think using git to manage your workflow makes sense? Sure I do, so I'll make it my workflow and not force it on any one else.

Ultimately, Jekyll's workflow is based around having a particular directory structure and putting things in the appropriate buckets in that structure. That's it. Whether or not we have helpers for that in Jekyll core is a discussion we need to have.

courajs · 2013-09-05T15:54:22Z

Whether or not we have helpers for that in Jekyll core is a discussion we need to have

👍

benbalter · 2013-09-05T19:34:19Z

@parkr agree with everything you're saying, and that's why I caveated that any tooling can't exclusively assume git, but one word of caution:

It's enforcing a workflow that isn't flexible... locking us and our users into a certain way of working

(setting aside the fact that regardless of implementation a draft command would be opt in and in no way exclusive), that's exactly what we're doing here by adding this command. There's going to be a workflow behind it either way. I'm just asking if we're building towards the best workflow.

Tooling and defaults are more powerful than you think. We're building Jekyll around a certain workflow as is. That workflow involves a _drafts folder, and moving files around. If I'm a new user and I go to docs and ask "what's the best way to draft a Jekyll post", and it says, don't bother with anything that's established, we've got our own way of doing things... that's setting forward a particular workflow.

A draft command would be additional tooling and would go a long way to set a standard workflow in a way that hasn't been done to date... I was simply asking not if that's a viable workflow, or lowest-common-denominator workflow, but if that's the best workflow that we can imagine, and if that's what we want to be making the default.

Yes, we can't assume Git (although I'd argue 80%+ of the time that's how Jekyll's managed) , but I'd rather build against the ideal workflow, and fall back when we have to, not settle for second best because it's what we've done in the past.

doktorbro · 2013-09-08T07:41:40Z

I've been giving this some thought, and I've actually started to open an issue several times called "deprecate drafts", but haven't gone through with it. I think drafts as a feature encourage the wrong workflow.

I agree 100 %. Git has already everything.

Jekyll’s draft feature is build for one-man-blogs of day dreamers who start 100 posts and never finish them. It’s not really multi-user ready.

BTW, the draft feature was forced 8 months ago by @scribu, the Wordpress guy. It’s a implementation of the Wordpress staging workflow, I always hated. How many people really use this feature since it’s introduced?

The fact it’s for posts only just shows how unnecessary draft is. Look at Jekyll’s documentation. It’s built with pages, not posts. Different contributors start new pages, make pull requests, get things done. There are ~~drafts~~ git branches for every type of page. It works without draft.

scribu · 2013-09-08T10:05:28Z

BTW, the draft feature was forced 8 months ago by @scribu, the Wordpress guy.

I don't remember strong-arming anyone to commit the drafts feature. Please don't distort history. #769

doktorbro · 2013-09-08T16:03:59Z

I don't remember strong-arming anyone to commit the drafts feature. Please don't distort history.

@scribu I mean you had implemented the whole feature. Please don’t split hairs.

If I look at the Jekyll powered blogs of the 6 participants in #769 I can’t see nobody who actually uses the draft feature.

@scribu, @FellowMD, @zsiegel: What is your experience with drafts?

Did you used the draft feature since v1.0.0?
How many percent of your blog posts since v1.0.0 was born in drafts?
Do you know active Jekyll only bloggers who periodically use the draft feature?

scribu · 2013-09-08T16:11:41Z

If I look at the Jekyll powered blogs of the 6 participants in #769 I can’t see nobody who actually uses the draft feature.

How exactly do you expect to see them using the feature?

Did you used the draft feature since v1.0.0?

Yes.

How many percent of your blog posts since v1.0.0 was born in drafts?

100%.

Do you know active Jekyll only bloggers who periodically use the draft feature?

I don't know any Jekyll only bloggers; sorry.

scribu · 2013-09-08T16:18:17Z

The fact it’s for posts only just shows how unnecessary draft is. Look at Jekyll’s documentation. It’s built with pages, not posts. Different contributors start new pages, make pull requests, get things done. There are drafts git branches for every type of page. It works without draft.

It sounds like you find the whole posts feature of Jekyll unnecessary, in which case complaining about drafts is just trolling.

parkr · 2013-09-08T16:56:31Z

@mojombo wanted a native drafts feature at the time. Maybe he's changed his mind, but I haven't heard from him in a month or so.

I really like our drafts feature as it is and don't see a reason to deprecate it. I'd be happy to add the alternative git-only workflow (using solely posts) to the docs under "working with drafts". @benbalter the biggest reasons I don't like the workflow you proposed are (1) the overhead of modifying the publish date of a post that is a WIP for more than a day is annoying; (2) no way to preview the PR on GH Pages. The _drafts workflow doesn't cover these either but the cost of moving my drafts to branches is too high if it doesn't offer something my current workflow doesn't.

doktorbro · 2013-09-08T20:48:15Z

How exactly do you expect to see them using the feature?

I search in their public blogs source for _drafts folder. Example: https://github.com/mojombo/mojombo.github.io. I see no _drafts folder here.

scribu · 2013-09-08T20:53:02Z

That's because it's ignored: https://github.com/mojombo/mojombo.github.io/blob/master/.gitignore#L1

I also ignore it for my own blog.

scribu · 2013-09-08T20:58:17Z

Granted, I also have two little bash scripts, so my workflow looks like this:

./bin/new-draft 'Some Title'  # creates _drafts/some-title.md and opens vim
...
./bin/publish _drafts/some-title.md

Without these little utilities, I can understand why drafts might seem unnecessary. That's what this ticket is trying to address.

benbalter · 2013-09-08T21:20:25Z

BTW, the draft feature was forced 8 months ago by @scribu, the Wordpress guy.

@scribu you and I have worked together before on WP unit tests, among other things. Please know, that I in no way intended to imply any impropriety on your part. ❤️ that we find ourselves working on such diverse projects together yet again. 😄

How many people really use this feature since it’s introduced?

Too many to deprecate it, which is why I never open the issue.

I'm not saying we should get rid of drafts. We can't at this point. My argument is that if we're going to be building new tooling around a feature, I'd love the feature to fit into a bigger vision, rather than just bolting on things because they make sense after we did something last week.

If we're going to invest the time in tooling to reduce a pain point, lets use it as an opportunity to make it easier to do the right thing, not easier to do what is arguably a janky work around.

Granted, I also have two little bash scripts... Without these little utilities, I can understand why drafts might seem unnecessary. That's what this ticket is trying to address.

Spot on. The feature as it is now lacks tooling. I think we can all assume that as a given.

the overhead of modifying the publish date of a post that is a WIP for more than a day is annoying;

This issue is designed to fix just that. The discussion is whether we should build towards a _drafts-bespoke workflow, or encourage even super-basic Git flow (think analogous to GitHub edit-fork-PR web interface but for Jekyll command line).

The _drafts workflow doesn't cover these either but the cost of moving my drafts to branches is too high...

Moving meaning placing each current draft in a branch? Totally agree, but I'd argue you're an edge case, or even if not, the feature's only been around since 1.0.

if it doesn't offer something my current workflow doesn't.

...which is why I'm proposing tooling that uses the branch workflow if the site is versioned in Git, otherwise falling back to the _drafts workflow. Encourage the best practice, support the rest.

scribu · 2013-09-08T21:44:06Z

Hey @benbalter!

...which is why I'm proposing tooling that uses the branch workflow if the site is versioned in Git, otherwise falling back to the _drafts workflow.

And you'd also have to account for the case where the site is versioned in Git, but _drafts is ignored.

As a more general note, you seem to be saying two slightly contradictory things:

let's figure out the best workflow.
let's support the branch-based workflow, because it's the best.

Pick one.

scribu · 2013-09-08T21:48:55Z

Nevermind that last note. I re-read the whole thread and the gist seems to be:

Let's add tooling for the branch-based workflow, because it's better; but, since we can't get rid of _drafts, let's support that too.

doktorbro · 2013-09-08T21:49:37Z

I understand your workflow. You don’t want to share your drafts with public, until they are ready to publish as a regular post. So it’s not only technical decision but also a psychological one. This method works for one-man blogs only. If you want to build a magazine with reporters, editors and so on, it doesn’t really work anymore.

The git based workflow scales for every team size. If you start a new branch article and write _posts/2013-09-11-article.md, you have a deadline that kicks your ass to finish the post in time. Then you can send your branch to your chief editor, she would merge it in the develop branch and see the big picture. The git is made for team work.

I hope the draft feature supports you by writing.

benbalter · 2013-09-08T21:55:19Z

You don’t want to share your drafts with public, until they are ready to publish as a regular post.

Which to clarify, you don't have to do with a branch-based workflow either. Just don't push the branch.

Also, having a bunch of drafts just sitting on my hard drive and not backed up anywhere would scare the 💩 out of me. To the ☁️!

scribu · 2013-09-08T22:11:21Z

The assumption is that git branches and _drafts are mutually exclusive.

But what's wrong with opening a pull request against a file in the _drafts folder (assuming it's not in .gitignore)?

doktorbro · 2013-09-08T22:16:30Z

Which to clarify, you don't have to do with a branch-based workflow either. Just don't push the branch.

Also, having a bunch of drafts just sitting on my hard drive and not backed up anywhere would scare the 💩 out of me. To the ☁️!

@benbalter I agree again. The current draft feature is just a little helper. The branch-based workflow is the most promising code writing style of today’s world.

benbalter · 2013-09-08T22:24:15Z

But what's wrong with opening a pull request against a file in the _drafts folder (assuming it's not in .gitignore)?

Totally valid question. 1) it's not proper git-flow (master is live, branches as development), and 2) two users collaborating on the same repository can't submit a pull request from master back onto master, you can't do line-by-line review or discuss a commit to master, or receive notifications about the commit... the idea is you'd want the initial draft prior to publishing to be the pull request, not subsequent revisions... you don't want a pull request to correct a typo on a draft just because it's already hit master.

doktorbro · 2013-09-08T22:27:45Z

And please remember the possible assets for your drafts: images, videos, archives, etc. The draft feature can not handle these files.

scribu · 2013-09-08T23:03:58Z

Ok, those are valid points.

How does Octopress handle drafts again?

benbalter · 2013-09-08T23:06:48Z

How does Octopress handle drafts again?

They use published: false (which Jekyll also recognizes as an alternative drafts workflow) which from a flow standpoint is essentially the same as _drafts (using a YAML flag rather than a file path flag to determine published status).

scribu · 2013-09-08T23:21:17Z

I don't know what to say. On the one hand, _drafts works best for single-author blogs (even without assets). On the other hand, branches work best for more serious publishing.

In both cases, the tooling doesn't really need to be shipped with Jekyll, so maybe it would be best to leave it for third-parties, for now. Maybe @benbalter will write an extension that will knock our socks off. :)

courajs · 2013-09-09T00:54:00Z

From a single author standpoint, it's really helpful to have many draft posts percolating in the background. I personally have my drafts on my Dropbox, with a symlink of _drafts->~/Dropbox/drafts. Professional writers may have one article they work on until it's done, but amateur single authors aren't sure what we want to publish until we've written it. Kicking my ass to meet a deadline isn't necessary.
From what I can see, the branch based workflow flat out breaks the ability to see all these evolving posts next to each other and see the bigger picture. Let me know if I'm wrong there.
It does seem there's a bit of tension between the ideal workflows of small and large blogs, but the project seemed to me to be weighted a bit toward the small blogger than the large blog even before I started using it

scribu · 2013-09-09T02:04:34Z

two users collaborating on the same repository can't submit a pull request from master back onto master, you can't do line-by-line review or discuss a commit to master, or receive notifications about the commit... the idea is you'd want the initial draft prior to publishing to be the pull request, not subsequent revisions... you don't want a pull request to correct a typo on a draft just because it's already hit master.

I think I phrased the question wrong. There's nothing stopping you from creating the draft in the branch. And whether you start off in the _drafts folder or in _posts, when merging into master, you will most likely need to rename the file.

So, I still think that the _drafts folder could be useful for both single-author and multi-author blogs.

scribu · 2013-09-09T02:11:08Z

From what I can see, the branch based workflow flat out breaks the ability to see all these evolving posts next to each other and see the bigger picture. Let me know if I'm wrong there.

You are correct.

courajs · 2013-09-23T15:25:19Z

Just pointing out his utility that I'll probably start using
https://github.com/mmcclimon/mr_poole

acairns · 2014-01-05T12:00:40Z

Stumbled across this when looking for a command to publish from _drafts to _posts.
Ended up writing a quick bash script: https://gist.github.com/acairns/8267431

$ ./bin/publish _drafts/my-new-post.md

Moves post and prefixes with current date.
It's quick and dirty, but hopefully someone finds it useful when searching.

MartinThoma · 2014-01-15T22:16:07Z

I have written a Python script for publishing drafts: https://github.com/MartinThoma/MartinThoma.github.io/blob/source/publish.py

It does the following:

Search in YAML (and only there) for ^date: (.*)$ and replace it by the current date in format %Y-%m-%d %H:%M
Create a new file with the content of the draft and a modified name like this:
- If the draft has a YYYY-MM-DD prefix, remove it
- use the name that it has
- if this results in a duplicate, add "-dup" to the name. Do this as often as necessary.
- Print the name so that the user can take manual action if the resulting name is not as desired

diabolo · 2014-01-31T15:14:53Z

I think you could close this issue now, as the mr_poole gem addresses the requirement to publish a draft without adding anything 'drafty' to jekkyl.

jashank · 2014-02-04T07:03:43Z

My $0.0.2:

I agree that an (effectively) enforced workflow is a Very Bad Idea; part of the appeal of Jekyll (to me, and I guess, to others) is it's flexibility;
Workflow management is very much a personal preference, and I suggest that a few such examples of Jekyll workflow tools (mr_poole or Rake tasks or custom scripts or whatever) be listed in the docs; and
When Allow "git style" jekyll-commands. #1972 happens, I suspect a gem that provides workflow tools would be a logical progression.

Otherwise, I agree, this shouldn't go in core.

parkr · 2014-05-10T21:09:45Z

Going to take care of this over in https://github.com/jekyll/jekyll-compose 😃

scribu mentioned this issue Sep 8, 2013

Continue work on write command #1395

Closed

4 tasks

troyswanson mentioned this issue Sep 9, 2013

Small but very useful tip on using jekyll on macosx when you use hoembrew #1504

Closed

doktorbro mentioned this issue May 6, 2014

Jekyll/GitHub workflow with hidden drafts? jekyll/jekyll-help#27

Closed

parkr closed this as completed May 10, 2014

jekyll locked and limited conversation to collaborators Feb 27, 2017

jekyllbot added the frozen-due-to-age label Feb 27, 2017

Jekyll command to publish a draft #1469

Jekyll command to publish a draft #1469

Comments

zsiegel commented Aug 28, 2013

courajs commented Aug 29, 2013

parkr commented Aug 29, 2013

parkr commented Aug 29, 2013

zsiegel commented Aug 29, 2013

mattr- commented Aug 29, 2013

benbalter commented Sep 4, 2013

courajs commented Sep 4, 2013

mattr- commented Sep 5, 2013

courajs commented Sep 5, 2013

parkr commented Sep 5, 2013

zsiegel commented Sep 5, 2013

mattr- commented Sep 5, 2013

courajs commented Sep 5, 2013

benbalter commented Sep 5, 2013

doktorbro commented Sep 8, 2013

scribu commented Sep 8, 2013

doktorbro commented Sep 8, 2013

scribu commented Sep 8, 2013

scribu commented Sep 8, 2013

parkr commented Sep 8, 2013

doktorbro commented Sep 8, 2013

scribu commented Sep 8, 2013

scribu commented Sep 8, 2013

benbalter commented Sep 8, 2013

scribu commented Sep 8, 2013

scribu commented Sep 8, 2013

doktorbro commented Sep 8, 2013

benbalter commented Sep 8, 2013

scribu commented Sep 8, 2013

doktorbro commented Sep 8, 2013

benbalter commented Sep 8, 2013

doktorbro commented Sep 8, 2013

scribu commented Sep 8, 2013

benbalter commented Sep 8, 2013

scribu commented Sep 8, 2013

courajs commented Sep 9, 2013

scribu commented Sep 9, 2013

scribu commented Sep 9, 2013

courajs commented Sep 23, 2013

acairns commented Jan 5, 2014

MartinThoma commented Jan 15, 2014

diabolo commented Jan 31, 2014

jashank commented Feb 4, 2014

parkr commented May 10, 2014