Add draft support for Markdown Content

[mimorocks]

this adds support for a draft property in your Markdown files

draft: true

This can mark content as Work-in-Progress that should not yet be included in your build site.

Site is build just from non-draft content then

default is draft = false for not defined property

[slashmo]

I like this change overall. 👍 I think isDraft would make for a more Swifty API.

[dpfannenstiel]

I was thinking about this problem this morning as well. Initially I was thinking that Draft should be another folder at the same level as Content. Then when the site is built with drafts on the draft content is included.

[mimorocks]

I was thinking about this problem this morning as well. Initially I was thinking that Draft should be another folder at the same level as Content. Then when the site is built with drafts on the draft content is included.

I had a different approach. In my thinking draft is a temporary toggle that is set for Content that is not yet completely finished and not yet ready for publishing.

I did not want to move around this kind of unfinished Content or put it elsewhere. My goal was to already have it in the Content folder.

The site is never build with draft content however.

[dpfannenstiel]

I have 3 concerns with the feature:

1. How difficult is it to find your drafts when you have 100 posts and 5 drafts all in the Content folder?
2. What is the use case if a user has implemented using a more complicated file structure than just putting markdown in Content for example year/month/day? And then they have to move it around after it is no longer a draft?
3. How much friction is there for users coming over from another static blogging platform like Jekyll which already uses the Draft folder?

[mimorocks]

I have 3 concerns with the feature:

1. How difficult is it to find your drafts when you have 100 posts and 5 drafts all in the Content folder?

It is as easy as doing a search for draft: true

2. What is the use case if a user has implemented using a more complicated file structure than just putting markdown in Content for example year/month/day? And then they have to move it around after it is no longer a draft?

I am not sure that I understood your example here. But if you have a structure that would not benefit from the lightweight draft switch or solves the problem in another way you could simply not use it.

3. How much friction is there for users coming over from another static blogging platform like Jekyll which already uses the Draft folder?

This would depend on where you are coming from. If you are coming from Hugo I.e. you would already be accustomed to the draft swift .

On the other hand: you would not have to use the draft switch at all. If one prefers to solve this via a folder structure this feature is not holding you back. But I would say this is a different feature than this lightweight draft switch solution.

[bizz84]

I have the same requirement in my website. Would love to use this. 🙂

[Ze0nC]

My concern is, If we choose not to process the markdowns marked with draft flag at all, how could someone preview the building result of the draft?
IMO, if we want to implement this draft feature as an official feature, the proper way might be process & output all drafts, but not to include them during deployment (when --deploy flag is on).

[bizz84]

@Ze0nC I'm doing this with some command line arguments:

These are parsed and passed as arguments to my Website subclass.

There may be other ways, but this works well for me.

[mimorocks]

My concern is, If we choose not to process the markdowns marked with draft flag at all, how could someone preview the building result of the draft?
IMO, if we want to implement this draft feature as an official feature, the proper way might be process & output all drafts, but not to include them during deployment (when --deploy flag is on).

This might be a thing. On the other hand: I did want to keep it simple and did not really see the need to preview the building result of a draft (It's Markow after all / you could temporarily remove draft while you are working on it and really need a preview).
And one could always add a dependency to the --deploy command line arguments or some other suitable configuration artefact later?

[bizz84]

For context, sometimes I cross post my articles to dev.to, and that site uses a published flag in the markdown metadata. New articles have it set to false by default, and publishing happens by setting it to true. That's a hosted solution, and deployment works differently with Publish obviously. But I like the concept of starting as a draft, and switching the flag when I'm ready to publish. Just becomes second nature after a while. Anyway just my .02

[dpfannenstiel]

I've found Jekyll's draft system to be incredibly simple. All drafts are kept in a drafts folder.

Consider the case where you have a long lead piece. This could be a well researched paper or an entry about an involved build that's in process. It could sit in drafts for weeks. Maybe you have an idea for a short story that you want to edit around. The scrap of something you don't want to lose, but isn't ready to be placed into your file structure.

Over a long enough period of time, your published work pieces is going to grow. They represent Done. Your drafts folder becomes your backlog. Things and ideas you're working on.

There are a lot of ways to have Publish directory trees structured to store your finished pieces. If you keep having drafts nested in something like /2020/11/18/article1.md you've got to go hunting for it.

Looking at this feature consider how does it affect the level of effort onboarding a user with minimal programming knowledge.

[JohnSundell]

I don't think Publish should have an opinion on how drafts should be handled, since different people will want to organize their drafts differently. For example, I'm with @dpfannenstiel, and personally don't think it's a good idea to mix drafts with production content (I use a dedicated Drafts folder at the root for that, and simply move an article into the Content folder when it's ready).

Since Publish already supports custom metadata, you could always implement the functionality that you're looking for by adding a draft property to your website's ItemMetadata type, and then write a custom PublishingStep that uses the removeItems API on Section to remove all drafts. This could also be bundled as a plugin to make that code reusable.

Another approach (that I would be willing to accept a PR for) would be to add a Predicate argument to the built-in addMarkdownFiles publishing step, which could then be used to filter out drafts before they're parsed (which would be more efficient than the above mentioned approach). I think that would be a much more generic and generally applicable solution than this proposed implementation.

So, I'm sorry, but this PR won't be accepted, as I don't think the current implementation should be a part of Publish's official API. Thanks anyway @mimorocks.