Metadata is the wrong abstraction, let's simplify

[dillonkearns]

Metadata is inverted

The original goal was to have a clear mapping - if you want to find out where the content for a page comes from, you can directly map the content's file name to the route.

That got it completely inverted. How do humans understand what page they're on? From the URL. That's all the information you have. It's just a string.

Conceptually, some of those pieces of the string are set (example.com/blog), and some of them have more dynamic information (/blog/post-1).

This is how users will make sense of URLs. So having that opinion built-in makes sense for a framework, too. This is why the NextJS file-based routing makes sense.

For looking up the data, I had it upside down with the initial elm-pages design. It was a good stepping stone, but not the long-term solution.

The idea of metadata in frontmatter on a page should not be what decides what page to render (as it is in the current formulation of the Template Modules beta). Instead, it's upside down: given a URL, you should be able to go gather the data you need. Including metadata, like a blog post's title, description, etc. Or the body. It doesn't really matter how you get those, just that if I tell you a URL, like "this is a blog post with slug post-123", then you can go look up all the data you need from there to render the page.

This will eliminate a lot of complexity in the current elm-pages and elm-pages template modules design. For example:

• Template Modules currently requires you to build a data type that has the metadata that a specific type of template will have. This has been confusing to explain, and I think it's because it was an awkward abstraction, and upside down as described above. Instead, now we will have something more like elm-spa, where conceptually you can match parts of a URL and have those as input data that let you look up a page. That mental model will be a lot simpler, and I think it might reduce boilerplate for writing a Page Module (also, we can call them Page Modules instead of Template Modules now!

Routing Implications

This has some drastic implications for routing. With the previous elm-pages Metadata concept (and Template Modules idea), you would have to get this Metadata type and somehow decode into that type to tell the router which page you're on.

This was particularly awkward when it came to more dynamic routes. That would mean that you would need to build up that data, but then you need to bundle the data you used to build that data up into the resulting page. Or else you need to have the user manually encode and decode it to JSON so you can be sure to keep the Metadata they ended up with. This made it extremely difficult to figure out how to do decoupled routing where you could, say, have routes for every blog post from some API-based CMS data source.

But with this new approach, all the information you need to render a page is its URL. From that information, you can look up all the data sources you need in order to statically generate some pages.

If you want to get fancy, then you can have a nice place to perform StaticHttp requests so you can easily get those URLs, and get them in a structured way based on the dynamic parts of the URL. Something like:

type alias Route = { postSlug : String }

prerenderedRoutes =
  staticHttpRequestForCms
  |> StaticHttp.map(\blogPosts ->
    blogPosts |> List.map (\post -> { postSlug = post.slug }
  )

Conclusion

So given all these insights, I'm now getting clarity that file-based routing, like NextJS or elm-spa is the way to go here. That's the right mental model that will allow us to get rid of the notion of Metadata as a first-class concept in elm-pages entirely.

Metadata shouldn't be something that elm-pages cares about. elm-pages only cares about data - not specific types of data. This simplifies the mental model a lot and is a more powerful abstraction.

Note that the ability to have files from the file system as a data source that can hook into any of the places that StaticHttp requests can will be a key feature for supporting this new architecture. That feature is being tracked in this issue: #122.