feat: Ability to switch "default" template processors

jaredcwhite commented 4 years ago

I'm increasingly concerned about the future of Liquid as a robust open source project, and that paranoia combined with the recent work to add Tilt support (ERB, etc.) is causing me to rethink Bridgetown's long-term template strategy.

To that end, I think it would be worthwhile to add the ability to switch the default template processor. In other words, standard files that send in .html or .md or .json could in theory be processed through ERB or Slim (or something else super-secret I may or may not be working on 😉) without having to use those exact template extensions.

Alternatively, we bite the bullet and adopt the multi-extension approach like other Ruby frameworks…blog-post.md.erb, projects.html.slim, etc. Maybe that's better in the long run, but it's definitely a major backwards-incompatible change so we should consider it carefully.

KonnorRogers commented 4 years ago

I like the idea of a default processor. I see the isssue if maybe you want certain one file to be parsed with one template and another file to be parsed with another.

Perhaps we could have path And exclude patterns that take in an Array of globbable paths.

IE:

default_processor:
  engine: "ERB"
  path: 
    - "./**/*"
  exclude:
    - "./**/*.slim"
    - "./**/*.haml"

wout commented 4 years ago

It makes a lot of sense to pick a processor and stick with it I think. I'm not a fan of mixing processors or having templates pulled through multiple templating engines. It's the same for a Rails project for example. Having Haml, ERB, Slim and Liquid templates in one project would be unnecessarily confusing. :)

I'm also for the multi-extension proposal because that makes it more clear what you're dealing with.

@jaredcwhite A bit off-topic, but I'm wondering about this statement:

I'm increasingly concerned about the future of Liquid as a robust open-source project

Why is that? I'd be really interested to hear the full story.

jaredcwhite commented 4 years ago

@wout There's definitely nuance to how the templates work because it's a common practice (and something I loved from the very first days of using Jekyll) to process a Markdown file through Liquid first so that you gain the ability to structure your content through the use of Liquid tags/filters. What then gets confusing is if you process, say, an ERB template file through Liquid (which technically can be done at the moment).

Essentially the idea of switching the default would be that Markdown, normal HTML, JSON, etc. files get processed not through the current configuration of Liquid but instead through something else (whether ERB or whatever).

Regarding Liquid, there have been only 4 gem releases in 4 years, the current state of master over there is wildly divergent from the latest gem release which came out in March 2019 (!), and most comments/inquiries on the GitHub project go noticeably unaddressed. Essentially it seems to be an in-house tool at Shopify, and the fact it's open source is an afterthought.

(A polar opposite example would be ViewComponent by GitHub which formed a robust and lively open source community from day one and gets a new release at least one a month.)

wout commented 4 years ago

What then gets confusing is if you process, say, an ERB template file through Liquid

Essentially the idea of switching the default would be that Markdown, normal HTML, JSON, etc. files get processed not through the current configuration of Liquid but instead through something else (whether ERB or whatever).

@jaredcwhite That's exactly what I meant with sticking to a templating engine. It's a good practise is choose one (ERB, Liquid, Slim, ...) and use it throughout the project to inject dynamic content into static templates like HTML, JSON and Markdown.

I haven't looked at the Liquid codebase for quite a while and didn't realise it was in such a bad state. It's sad to see...

jaredcwhite commented 4 years ago

All right folks, I think I successfully cracked this nut. With PR #157 you can:

Set a template_engine key in your config file. The default is assumed to be liquid, but you can change it to erb (or other things in the future as this gets rolled out). Once that is set, you don't even have to name all your ERB files with an .erb extension—it will process even .html., .md, .json, etc. It also means Liquid won't try to "preprocess" any ERB files, etc..
Regardless of what is configured site-wide, you can also set the template_engine in front matter (whether that's in an individual file or using front matter defaults), allowing you to swap out template engines wherever it's needed. So if you switch to ERB but need to keep some documents, layouts, whatever, as Liquid, that's totally doable. Or visa-versa. For example I switched the Bridgetown website's default layout to ERB just by adding template_engine: erb to the front matter.

A side bonus is you could use front matter defaults to set template_engine: none to a folder or folder tree (say, a bunch of Markdown files that don't need to be Liquid, ERB, or anything else) and improve your build performance a smidge.

The main takeaway here is that Liquid is no longer guaranteed to have privileged status in Bridgetown. In an updated PR I'd like to move Liquid processing out of the core render path and into its own Converter object, so that it works in exactly the same way as ERB or any other converter plugin.

Rolling this out will require a bit of a coordinated effort across the ecosystem, as any plugins which supply their own pages or layouts using Liquid will need to add template_engine: liquid to their front matter, or use the .liquid extension (still TODO). Thankfully that won't be too painful at this stage.

Let me know your feedback!

KonnorRogers commented 4 years ago

No feedback here, seems like a great way to be template agnostic and allow people to pick and choose.

bridgetownrb / bridgetown

feat: Ability to switch "default" template processors #132