New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Allow front matter to be optional for pages #5209

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
7 participants
@benbalter
Contributor

benbalter commented Aug 7, 2016

This changes the reader logic to allow markdown Pages to be rendered without front matter.

The idea being, that with Themes available in 3.2, a site could be as simple as a config file that requests a theme, and a series of Markdown files.

For simple "hello world" sites, this flag would remove the step of having to learn what front matter is, and add it to a markdown file.

Right now I implemented a front_matter_optional config flag, which default to false. When set, any file, for which a converter is available, regardless of if it has YAML front matter, will be read in as a page.

If there's interest in this feature, I can work on adding tests, but wanted to pause before I went too far down the rabbit hole.

For context, I'd like to add this feature because with GitHub Pages, we can set a default theme, and a default template in our configuration defaults. That means that a user could have their first website by literally just creating a markdown file, no need to learn what YAML front matter is, or worry about adding it to each file.

This could be alternatively implemented as a plugin, but I think it's cleaner to adjust how files are read in, rather than reading them in as a second pass and rendering them independently.

@envygeeks

This comment has been minimized.

Show comment
Hide comment
@envygeeks

envygeeks Aug 10, 2016

Contributor

I'm on the fence with this, not because I don't like the idea, but because it also makes way more sense for posts too, where most of the data can be inferred from the path, unless the user wants to get ultra specific. I would like to see this extended to posts as well.

Contributor

envygeeks commented Aug 10, 2016

I'm on the fence with this, not because I don't like the idea, but because it also makes way more sense for posts too, where most of the data can be inferred from the path, unless the user wants to get ultra specific. I would like to see this extended to posts as well.

@jake-low

This comment has been minimized.

Show comment
Hide comment
@jake-low

jake-low Aug 11, 2016

@envygeeks: based on my investigations in #5064 (here's a direct link) frontmatter for posts is already optional. This was just a simple test of one version of Jekyll though, it's certainly possible that there's complexity I failed to discover.

Anyway, I'm in favor of a change like this, because as far as I can tell it reduces the difference between _posts and other document types. My initial foray was related to collections (correct me if I'm wrong, but I believe pages is not a collection), but in general making Jekyll more flexible for advanced use cases by reducing the "magic" around posts, pages, and data (but keeping sane defaults for a blog-plus-pages type site, to remain friendly for new users) seems like a worthy goal to me.

Wrt. configuration, would it be easy to make the setting controlling whether frontmatter is optional scoped per-collection, rather than globally? It seems to me that this would be more friendly to backwards-compatibility since the default for _posts could be true, but other collections could default to false.

jake-low commented Aug 11, 2016

@envygeeks: based on my investigations in #5064 (here's a direct link) frontmatter for posts is already optional. This was just a simple test of one version of Jekyll though, it's certainly possible that there's complexity I failed to discover.

Anyway, I'm in favor of a change like this, because as far as I can tell it reduces the difference between _posts and other document types. My initial foray was related to collections (correct me if I'm wrong, but I believe pages is not a collection), but in general making Jekyll more flexible for advanced use cases by reducing the "magic" around posts, pages, and data (but keeping sane defaults for a blog-plus-pages type site, to remain friendly for new users) seems like a worthy goal to me.

Wrt. configuration, would it be easy to make the setting controlling whether frontmatter is optional scoped per-collection, rather than globally? It seems to me that this would be more friendly to backwards-compatibility since the default for _posts could be true, but other collections could default to false.

@benbalter

This comment has been minimized.

Show comment
Hide comment
@benbalter

benbalter Sep 6, 2016

Contributor

/cc @jekyll/build as the appropriate affinity team for feedback on the proposal.

Contributor

benbalter commented Sep 6, 2016

/cc @jekyll/build as the appropriate affinity team for feedback on the proposal.

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Sep 6, 2016

I'm 👎 on this, front matter is explicit, when you omit it you're telling Jekyll it's a plain file that it shouldn't touch.

ghost commented Sep 6, 2016

I'm 👎 on this, front matter is explicit, when you omit it you're telling Jekyll it's a plain file that it shouldn't touch.

@benbalter

This comment has been minimized.

Show comment
Hide comment
@benbalter

benbalter Sep 6, 2016

Contributor

you're telling Jekyll it's a plain file that it shouldn't touch.

@spudowiar Can you talk a bit more about when you think a user would have a .md file in their site that they'd want served as raw plaintext?

Contributor

benbalter commented Sep 6, 2016

you're telling Jekyll it's a plain file that it shouldn't touch.

@spudowiar Can you talk a bit more about when you think a user would have a .md file in their site that they'd want served as raw plaintext?

@fricklerhandwerk

This comment has been minimized.

Show comment
Hide comment
@fricklerhandwerk

fricklerhandwerk Sep 10, 2016

Big +1 @benbalter

no need to learn what YAML front matter is

since that was a noticable road block to overcome when adopting Jekyll as a newcomer. For non-programmers I assume it to be a real obstacle.

Also +1 @jake-low

reducing the "magic" around posts, pages, and data

I still think that they all should be the same. Posts have a date in the filename, everything else is a page. Data has data converters e.g. for .json or .yaml - then it just goes to the data dict. More data in the headers (optional). If there is no converter for the file type, copy verbatim.

fricklerhandwerk commented Sep 10, 2016

Big +1 @benbalter

no need to learn what YAML front matter is

since that was a noticable road block to overcome when adopting Jekyll as a newcomer. For non-programmers I assume it to be a real obstacle.

Also +1 @jake-low

reducing the "magic" around posts, pages, and data

I still think that they all should be the same. Posts have a date in the filename, everything else is a page. Data has data converters e.g. for .json or .yaml - then it just goes to the data dict. More data in the headers (optional). If there is no converter for the file type, copy verbatim.

@fricklerhandwerk

This comment has been minimized.

Show comment
Hide comment
@fricklerhandwerk

fricklerhandwerk Sep 11, 2016

@tgragnato non-programmer ≠ tech-unsavvy

fricklerhandwerk commented Sep 11, 2016

@tgragnato non-programmer ≠ tech-unsavvy

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Sep 11, 2016

non-programmer ≠ tech-unsavvy

👍

Non-programmer might be our target audience, but not tech-unsavvy

ghost commented Sep 11, 2016

non-programmer ≠ tech-unsavvy

👍

Non-programmer might be our target audience, but not tech-unsavvy

@benbalter

This comment has been minimized.

Show comment
Hide comment
@benbalter

benbalter Sep 11, 2016

Contributor

While the appropriateness and scope of this proposal within Jekyll core is being discussed, I created a lightweight plugin to implement the behavior: https://github.com/benbalter/jekyll-optional-front-matter.

Contributor

benbalter commented Sep 11, 2016

While the appropriateness and scope of this proposal within Jekyll core is being discussed, I created a lightweight plugin to implement the behavior: https://github.com/benbalter/jekyll-optional-front-matter.

@bytesandwich

This comment has been minimized.

Show comment
Hide comment
@bytesandwich

bytesandwich Sep 11, 2016

I can see the usefulness for a lot of people. However, this is a
substantial backwards incompatible change to a core invariant in Jekyll's
processing. There is a pretty strong statement in the docs:
https://jekyllrb.com/docs/plugins/#converters that this will never happen.
It's a big deal to abandon something like that.

On Sun, Sep 11, 2016 at 12:41 PM, Ben Balter notifications@github.com
wrote:

While the appropriateness and scope of this proposal for Jekyll core is
being discussed, I created a lightweight plugin to implement the behavior:
https://github.com/benbalter/jekyll-optional-front-matter.


You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub
http://t.sidekickopen65.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nMJW7t5XZs4X9HtMW63Bt382BpscdVd0r_-56dRNRf4kf01202?t=https%3A%2F%2Fgithub.com%2Fjekyll%2Fjekyll%2Fpull%2F5209%23issuecomment-246189849&si=5160750532526080&pi=4ce12a98-0497-44ba-a4ff-f7389c304c4e,
or mute the thread
http://t.sidekickopen65.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nMJW7t5XZs4X9HtMW63Bt382BpscdVd0r_-56dRNRf4kf01202?t=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FABAAbZQxLkdVc_HpyU8YNzxKgJ5n6q4uks5qpC9GgaJpZM4JeZHh&si=5160750532526080&pi=4ce12a98-0497-44ba-a4ff-f7389c304c4e
.

bytesandwich commented Sep 11, 2016

I can see the usefulness for a lot of people. However, this is a
substantial backwards incompatible change to a core invariant in Jekyll's
processing. There is a pretty strong statement in the docs:
https://jekyllrb.com/docs/plugins/#converters that this will never happen.
It's a big deal to abandon something like that.

On Sun, Sep 11, 2016 at 12:41 PM, Ben Balter notifications@github.com
wrote:

While the appropriateness and scope of this proposal for Jekyll core is
being discussed, I created a lightweight plugin to implement the behavior:
https://github.com/benbalter/jekyll-optional-front-matter.


You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub
http://t.sidekickopen65.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nMJW7t5XZs4X9HtMW63Bt382BpscdVd0r_-56dRNRf4kf01202?t=https%3A%2F%2Fgithub.com%2Fjekyll%2Fjekyll%2Fpull%2F5209%23issuecomment-246189849&si=5160750532526080&pi=4ce12a98-0497-44ba-a4ff-f7389c304c4e,
or mute the thread
http://t.sidekickopen65.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nMJW7t5XZs4X9HtMW63Bt382BpscdVd0r_-56dRNRf4kf01202?t=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FABAAbZQxLkdVc_HpyU8YNzxKgJ5n6q4uks5qpC9GgaJpZM4JeZHh&si=5160750532526080&pi=4ce12a98-0497-44ba-a4ff-f7389c304c4e
.

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Sep 16, 2016

Member

@benbalter You wrote a plugin for this – does that suffice for you or do you still think this should be a core feature? I could really go either way. It must be opt-in if it is placed in core. Thanks!

Member

parkr commented Sep 16, 2016

@benbalter You wrote a plugin for this – does that suffice for you or do you still think this should be a core feature? I could really go either way. It must be opt-in if it is placed in core. Thanks!

@benbalter

This comment has been minimized.

Show comment
Hide comment
@benbalter

benbalter Sep 19, 2016

Contributor

do you still think this should be a core feature?

I never understood why Markdown Pages required front matter (possibly "do what you ask, no more no less"), but do not have the time to see this through myself. If someone else would like to pick things up, I'd be 👍 but am not strongly opinionated.

Contributor

benbalter commented Sep 19, 2016

do you still think this should be a core feature?

I never understood why Markdown Pages required front matter (possibly "do what you ask, no more no less"), but do not have the time to see this through myself. If someone else would like to pick things up, I'd be 👍 but am not strongly opinionated.

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Sep 19, 2016

Member

I never understood why Markdown Pages required front matter (possibly "do what you ask, no more no less")

Yeah this dates back to well before I started. The idea was that conversion was opt-in, I think. I'd have to ask an old-timer but they might not even remember.

Will close this out for now then as the plugin satisfies this. Thanks!

Member

parkr commented Sep 19, 2016

I never understood why Markdown Pages required front matter (possibly "do what you ask, no more no less")

Yeah this dates back to well before I started. The idea was that conversion was opt-in, I think. I'd have to ask an old-timer but they might not even remember.

Will close this out for now then as the plugin satisfies this. Thanks!

@parkr parkr closed this Sep 19, 2016

@parkr parkr deleted the front-matter-optional branch Sep 19, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment