Consider renaming "permalinks" to "defaults"

[budparr]

I hope this is helpful feedback. These thoughts are primarily in consideration of Jekyll users' potential adoption (having built 30 or more Jekyll sites and knowing a lot of users and use-cases).

In the docs you suggest using permalinks like so:

function permalink (path) {
  const matches = path.match(/^(\d+-\d+-\d+-)/)
  if (!matches || !matches[1]) {
    throw new Error(`incorrect date formatting for post: ${path}`)
  }
  return { date: matches[1] }
}

Which, I think, adds a date object to locals, but it doesn't actually manipulate the permalink. Permalinks output right now to /posts/9-27-2016-second-post.sgr (which, as a separate issue/pr should be .html and not .sgr), but, if a "Jekyll" style is what you're after, it would instead output to /2016/09/27/second-post/.

I would expect that "permalinks" would manipulate the output URLs. Jekyll users would expect some sort of abstraction for permalink styles (e.g. "pretty"). Blogs are one thing, as they sometimes use categories in links; extension or no extension, etc.

Collections in Jekyll generally output either the collection name and baseurl, or something else defined in the config, as opposed to the current state where output URLs are merely a dump of the items' directories. And, Jekyll collections have the option to not output at all, but just to be used in templates.

So to recap: "permalink" should give the user a way to manipulate a collection's output URL scheme, regardless of the collection's source directory.

Furthermore, I've been playing around with using permalink as a way to set a default value:

permalink: (p) => { return { foo: 'bar' } },

Which suggests another use case for a function here, which is actually pretty powerful, and why I suggest changing, or making a separate option for defaults.

Hope that's helpful. I'm happy to work on a pr for whatever I might be capable of, which, by the way of an embarrassing example, I've been trying to work on the issue where _path incorrectly outputs .sgr for a long while with no success, but I can open a separate issue for.

[jescalan]

Thank you, this is super helpful! Will address this early next week if I can 😁

[jescalan]

Ok so I am way late on the next week promise haha, sorry! Taking another look at this now and hoping to implement shortly.

I like the suggestion of changing it to defaults. It currently does change the output url actually, it just doesnt nest it inside multiple layers of folders, since I thought this seemed silly to do this. However, if this is something that jekyll users enjoy and are accustomed to, we could definitely add it in!

So here's what I'm thinking. We'll make a new transform option that gets the post's full front matter and allows you to add to/remove from it, which would make it possible to just modify certain posts, or add a default across the board. Then we'll modify the permalinks functions such that it is able to create folders, and change the example to one that shows how to do this in the same way that jekyll does.

Does this seem like a reasonable approach? I'll start working on this soon 😁

cc @budparr

[budparr]

We'll make a new transform option that gets the post's full front matter and allows you to add to/remove from it, which would make it possible to just modify certain posts, or add a default across the board. Then we'll modify the permalinks functions such that it is able to create folders, and change the example to one that shows how to do this in the same way that jekyll does.

Yes, all around. I like calling it "transforms."

[jescalan]

Fantastic, just finished implementing this and it's working great. I'm going to also implement a permalinks option that modifies the output path as expected then ship that as an update, hopefully this will be a lot better for people coming from jekyll afterwards! Thanks again so much for your suggestions, and sorry it took me so long this time to get them done.

[budparr]

Excellent. I'll circle back around again soon and see what else I can break :)

[jescalan]

Amazing, thank you again!

[jescalan]

Ok so this was closed in the latest version. Whoo!