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

Inconsistent behavior with Posts and user-defined collections #7296

Open
ashmaroli opened this Issue Oct 4, 2018 · 7 comments

Comments

Projects
None yet
3 participants
@ashmaroli
Copy link
Member

ashmaroli commented Oct 4, 2018

This is simply to document the different behavior with Jekyll's "default collection" posts and "user-defined collections"..

  Posts User Collections
Filename Format YY(YY)-M(M)-D(D)-title.extn N/A
Front matter Optional Mandatory
Categories & Tags Supported Not Supported
Categories from superdirs Supported Not Supported
Location _posts can be located anywhere within config["collection_dir"] _#{label} has to be at root of config["collection_dir"]
URL Template <date>* /:collection/:path
Static File Siblings Ignored Loaded into collection.files
*<date> : /:categories/:year/:month/:day/:title:output_ext
@ghost

This comment has been minimized.

Copy link

ghost commented Oct 4, 2018

Personally, I believe it'd benefit Jekyll if everything except the optional Frontmatter was the same between the two. In lieu of user-friendliness, we should still allow users to waive frontmatter on posts.

@DirtyF

This comment has been minimized.

Copy link
Member

DirtyF commented Oct 4, 2018

Front Matter

If posts or collection documents don't have a date in their filename, we pick the date from the front matter
If posts or collection documents have a date in their filename, we extract the date from the filename

Permalinks

As users can override permalinks for collections, we could set a different default for posts collection:

permalinks: /:collection/:path

collections:
 posts:
    output: true
    permalink: /:categories/:year/:month/:day/:title:output_ext

Static files

We will have to write some common scenarios to figure out how to deal with static files in collections.
Would be nice to autolink a document with files when they're in the same folder so that you can easily access those in your layouts.

 

Summary:

  Posts User Collections
Filename Format YY(YY)-M(M)-D(D)-title.ext or title.ext YY(YY)-M(M)-D(D)-title.ext or title.ext
Front matter Optional Mandatory
Categories & Tags Supported Supported
Categories from superdirs Supported Supported
Location posts has to be at root within config["collection_dir"] _#{label} has to be at root of config["collection_dir"]
URL Template /:categories/:year/:month/:day/:title:output_ext /:collection/:path
Static File Siblings Loaded into collection.files Loaded into collection.files
@kimbaudi

This comment has been minimized.

Copy link
Contributor

kimbaudi commented Feb 16, 2019

So .md files in Pages and Posts do not require front-matter to convert to .html files, but .md files in Collections require front-matter to convert to .html files... 😞

Personally, I wish this part was consistent. Either require front-matter in all .md files (Pages, Posts, Collections) or don't require.

Since I don't want to put empty front-matter each time I create a new .md file for my collections just to render it to .html, I wish front-matter is not required in any .md file. We can get front matter defaults from _.config.yml.

At the moment, I need to add empty front-matter to all my .md files in my collections in order to render it as .html even though I set defaults in my _config.yml. I hope this changes in the future. 🙏

@ashmaroli

This comment has been minimized.

Copy link
Member Author

ashmaroli commented Feb 16, 2019

@kimbaudi Actually, only Posts (any valid convertable extension) do not require front matter to be converted to HTML Pages.
Everything else, Pages or other Collection documents require front matter to be converted to HTML.

Jekyll uses the front matter to decide whether to consider a file as "convertable" or "non-convertable (static)" based on the presence of front natter. Posts get the leeway because of their unique filename pattern.

@kimbaudi

This comment has been minimized.

Copy link
Contributor

kimbaudi commented Feb 16, 2019

@ashmaroli, both Pages and Posts do not require front matter for md files to be converted to .html files. (Note: Pages mean any .md file in the root directory. Posts mean any .md file with a valid yyyy-mm-dd date format in the filename in the _posts directory.)

Unfortunately, only Collections require front matter for .md files to be converted to .html files. (Note: Collections mean any .md file in the _name_of_collection directory.)

Since Pages and Posts (i.e., files under / and /_posts/) do not require front matter in .md files, I expected Collections (i.e., files under _name_of_collection) to also not require front matter in .md files. However, this is not the case for me with jekyll v3.7.4.

You seem to suggest that Pages require front matter in .md files, but that is not the case for me. What version of jekyll are you using? The current version 3.8.5?

btw, I am using the latest "github-pages" gem, which uses jekyll v3.7.4.

@ashmaroli

This comment has been minimized.

Copy link
Member Author

ashmaroli commented Feb 16, 2019

both Pages and Posts do not require front matter

@kimbaudi I wouldn't blame you for arriving at that conclusion. But the truth is that the reason you feel so is because of this plugin automatically loaded by github-pages.

If you were to build a site using just plain Jekyll (any version), then you'll realize that GitHub Pages and Jekyll produce slightly different results out-of-the-box.

@kimbaudi

This comment has been minimized.

Copy link
Contributor

kimbaudi commented Feb 16, 2019

@ashmaroli thank you for clarifying that jekyll-optional-front-matter is the reason why Pages do not require front matter. I will just continue to use the jekyll-optional-front-matter plugin since I really don't want to add front matter to each .md file for Pages. And I will just add front matter to each .md file for Collections until there is a way to optionally add front matter for Collections (using a plugin or a future Jekyll version).

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