Discuss Grav CMS as alternative to Grow

Objective

Agree on that Grav CMS is a coequal replacement for Grow while offering some additional features that come in handy, during the relaunch of the platform.

Background

During our on-site workshop in Hamburg we discussed the point that Grow might lack some features that would help creating an easily maintable platform. Although Paul asked us to not spend too much time on it we had enough capacity in the development team during our second sprint to prove that Grav CMS is a valid option and offers all of the requested features and some more with #63. Below I summarized our findings in the context of the points we adressed during our meeting and some thoughts on other useful features.

To see for yourself you are welcome to either checkout amp.dev/grow-alternatives on your local machine and run the following command from ~/grav

php -S localhost:8080 system/router.php

and access your local instance by visiting localhost:8080 or alternatively visit our hosted demo instance and its admin interface to quickly have look. You should have received crendentials - if not please give me quick hint :slightly_smiling_face:

i18n

Grow has a good built-in internationalization support which comes down to .po files to manage interface texts and markdown files for each language. Good news: Grav CMS basically works virtually the same. Just that instead of .po files the interface texts are residing in a languages.yaml file. Apart from that as requested all different language versions of a document will stay together with their parent document as you can see in ~/grav/user/pages/02.styleguide/01.molecules/tip.

Component complexity

Eventhough Paul introduced really human way to add special components to the current content documents (just write Tip: for a tip!) with ampproject/docs/#1119 we fear that some of our components and/or layouts need a more descriptive way to be intuitively maintainable. Although the foundation to achieve this is there in Grow it is already implemented in Grav CMS when using the official grav-shortcode-core plugin.

It offers the possibility to, for example simply pull in sections of contents into a template just like in the template of the styleguide detail page by using the BBCode [section name="*"] in the content documents.

The approach of BBCodes could also be used to establish complex components like the float image for which we exemplarily implemented the [float-image] shortcode. Others currently implemented to prove the concept are [tip] and [stage].

Implementing such a shortcode is as easy as adding a fitting class to ~/grav/user/themes/amp-dev/classes/shortcodes/ - this is also were you find the implementations of the currently available shortcodes.

Data asset management

The planned relaunch will bring in a lot of pictures in to the game to make things a bit more visually appealing and relatable. Anyhow Grow only offers to route static assets via the podspec.yaml which decouples images and other assets from their content documents.

Grav CMS though holds assets together with them and also makes them easily accessible in the admin interface.

Additionally Grav has built-in support for on the fly image modifications by appending GET parameters to image URLs just like on the float-image demo page.

Asset pipeline

Adding dependencies to the Grow Site is currently done by frontmatter. An alternative would be some kind of middleware that scans the generated markup for <amp-* tags and then injects the needed libraries.

In our demo we extended Grav's default asset manager which now offers the functionality to add AMP dependencies from anywhere: may it be from any of our templates by calling {% do assets.addAmpComponent('amp-fx-collection') %} like in ~/frontend/source/twig/partials/shortcodes/float-image.html.twig or from our backend code by calling $grav['assets']->addAmpComponent('amp-animation');. Those calls get then lazily evaluated to add every registered dependency only once. And only if needed.

The same functionality could be used to add only CSS to the page that is really needed. Therefore the logic of each shortcode would inject its styles by calling the asset manager's addCss() method. This saves us from hand-crafting matching CSS bundles for our templates which still might include unused components.

User interface

We see that this is not a major pain point. But having something visual to maintain the site for someone who is not that well versed in handling a repository with files doesn't hurt. Additionally the whole admin functionality is optional and at its core is nothing more than an official plugin.

Besides offering a UI to edit the content documents it is possible to craft custom authoring UIs by using blueprint.yaml files for matching templates. This way for example an events detail page could have a different UI than the default template, by just a few lines of YAML.

Being a static site

Apart from all the fancy CMS features we still want the new amp.dev to be a static site. And this might be the biggest hurdle as Grav CMS is not a static site generator by design but a CMS. However there are plugins like grav-plugin-blackhole which you might try by running the following command from ~/grav

bin/plugin blackhole generate http://localhost:8080 --output-url http://amp.dev --output-path ../build/ --assets

Sadly the output is not really satisfying although it might be a good starting point for a own static site generator solution. The good thing though is that the Grav Team has the option for a full static option on its roadmap for Grav 2 in getgrav/grav/#1767 which we may support.

Summary

The above is just a quick overview over the core aspects of a possible switch. One major point is missing though: Grav is event based and therefore offers a lot of hooks that make it easily extendible - like we already did for some of the examples.

Also the proposal is not random: I did use Grav CMS for manhattan-freund.de and clara-andrada.com and hence have some experience with it.

As a Python lover I am not 100% comfortable to suggest switching to PHP-based Grav. But I definitely consider it to be the better fit for our use case.

i18n

Grow has a good built-in internationalization support which comes down to .po files to manage interface texts and markdown files for each language. Good news: Grav CMS basically works virtually the same. Just that instead of .po files the interface texts are residing in a languages.yaml file. Apart from that as requested all different language versions of a document will stay together with their parent document as you can see in ~/grav/user/pages/02.styleguide/01.molecules/tip.

mhh, the messages.po files seem much more powerful in practise, as there's an automatic string extraction process, and all localization vendors can work with the po files. The YAML file seems very much like the yaml strings that we sometimes use in the front matter in Grow, but not much more. I definitely think Grow wins here.

Component complexity

Eventhough Paul introduced really human way to add special components to the current content documents (just write Tip: for a tip!) with ampproject/docs/#1119 we fear that some of our components and/or layouts need a more descriptive way to be intuitively maintainable. Although the foundation to achieve this is there in Grow it is already implemented in Grav CMS when using the official grav-shortcode-core plugin.

I'd definitely like to keep the ability to just write Tip: and have it auto convert. It's super neat. If Grav can't do that, then that's pretty sad. I'm also wondering how Twig performs generally compared to Jinja2.

In addition, I was planning on using the same Grow infrastructure to convert markdown images into <amp-img> blocks.

Data asset management

The planned relaunch will bring in a lot of pictures in to the game to make things a bit more visually appealing and relatable. Anyhow Grow only offers to route static assets via the podspec.yaml which decouples images and other assets from their content documents.

Grav CMS though holds assets together with them and also makes them easily accessible in the admin interface.

Not sure how I feel about that, I actually think a global asset folder is a feature, not a bug :) But I could go either way.

Asset pipeline

Adding dependencies to the Grow Site is currently done by frontmatter. An alternative would be some kind of middleware that scans the generated markup for <amp-* tags and then injects the needed libraries.

This seems easy enough in Grow with the new plugin architecture.

In our demo we extended Grav's default asset manager which now offers the functionality to add AMP dependencies from anywhere: may it be from any of our templates by calling {% do assets.addAmpComponent('amp-fx-collection') %} like in ~/frontend/source/twig/partials/shortcodes/float-image.html.twig or from our backend code by calling $grav['assets']->addAmpComponent('amp-animation');. Those calls get then lazily evaluated to add every registered dependency only once. And only if needed.

This still seems fairly manual to me. I just want all of this automated away.

The same functionality could be used to add only CSS to the page that is really needed. Therefore the logic of each shortcode would inject its styles by calling the asset manager's addCss() method. This saves us from hand-crafting matching CSS bundles for our templates which still might include unused components.

This makes sense.

User interface

We see that this is not a major pain point. But having something visual to maintain the site for someone who is not that well versed in handling a repository with files doesn't hurt. Additionally the whole admin functionality is optional and at its core is nothing more than an official plugin.

This is definitely neat, but it would make much more sense to switch fully to WordPress then, as we literally have a team working on building the best AMP editing experience for a CMS w/ WordPress.

Summary

As a Python lover I am not 100% comfortable to suggest switching to PHP-based Grav. But I definitely consider it to be the better fit for our use case.

I will say PHP makes me a little nervous. Did you evaluate more CMS / site generators? Grav seems similarly small as Grow in terms of contributions and overall activity.

So far, I didn't have a "oh wow this is much better than Grow" feeling, but looking forward to hear @sebastianbenz and @rsimha's opinions.

Thanks for your detailed feedback, @pbakaus. Really appreciate it.

mhh, the messages.po files seem much more powerful in practise, as there's an automatic string extraction process, and all localization vendors can work with the po files. The YAML file seems very much like the yaml strings that we sometimes use in the front matter in Grow, but not much more. I definitely think Grow wins here.

That is actually a very valid concern, as it is still YAML without any superpowers. Though my experience with .po files from various Django projects is that they become incredibly messy, especially if multiple people are working on the translation targets, but that is more like my personal preference.

I'd definitely like to keep the ability to just write Tip: and have it auto convert. It's super neat. If Grav can't do that, then that's pretty sad. I'm also wondering how Twig performs generally compared to Jinja2.

I totally agree that the Tip: expansion is a clever way of extending the documents as it hardly is a type of syntax you need to learn. Still I am concerned on how we are going to deal with some of our more complex, new components. Maybe we stick with the Float image as an example case: the first idea I had was that simply two consecutive images make up a Float image component. But of course this does not always work; therefore I reached out to those BBCodes, which would introduce a new, non-default syntax that one needs to learn. Something I am also not really happy with. At least I found it easier to use than {% callout %}. I am curious wether you had already spent some thoughts on this :slightly_smiling_face:

This still seems fairly manual to me. I just want all of this automated away.

I am a bit torn on this one. Although I like automating this for content editors I am feeling a little uneasy on the aspect that any kind of injection magic might be unpredictable. That is why I liked registering used components from used template partials. But either the registration approach and the automatic one would work in both systems. Howsoever for which system we will settle I would love to implement the CSS bundle thing.

as we literally have a team working on building the best AMP editing experience for a CMS w/ WordPress.

Yep! Thought about this one as well but then remembered that we wanted to stick to a file-based solution especially to have a version controlled documentation. However using Wordpress would be a big step towards its community - saying that unbiased.

Did you evaluate more CMS / site generators? Grav seems similarly small as Grow in terms of contributions and overall activity.

None as detailed as Grav though I gave Kirby (did not like: licensing, driven by a single person) and Automad (did not like: sadly litteraly only one contributor, custom template engine) a shot. Regarding PHP itself I think we are on the same page. Something I found beneficial though is that something like a amp-component-auto-injector written in PHP would benefit every AMP/PHP project.

Thanks for your detailed feedback, @pbakaus https://github.com/pbakaus. Really appreciate it.

mhh, the messages.po files seem much more powerful in practise, as there's an automatic string extraction process, and all localization vendors can work with the po files. The YAML file seems very much like the yaml strings that we sometimes use in the front matter in Grow, but not much more. I definitely think Grow wins here.

That is actually a very valid concern, as it is still YAML without any superpowers. Though my experience with .po files from various Django projects is that they become incredibly messy, especially if multiple people are working on the translation targets, but that is more like my personal preference.

Fair enough. The grow extraction process worked OK for us so far, but there's always room for improvement.

I'd definitely like to keep the ability to just write Tip: and have it auto convert. It's super neat. If Grav can't do that, then that's pretty sad. I'm also wondering how Twig performs generally compared to Jinja2.

I totally agree that the Tip: expansion is a clever way of extending the documents as it hardly is a type of syntax you need to learn. Still I am concerned on how we are going to deal with some of our more complex, new components. Maybe we stick with the Float image http://amp-dev.projects.anyvent.org/en/styleguide/molecules/float-image as an example case: the first idea I had was that simply two consecutive images make up a Float image component. But of course this does not always work; therefore I reached out to those BBCodes, which would introduce a new, non-default syntax that one needs to learn. Something I am also not really happy with. At least I found it easier to use than {% callout %}. I am curious wether you had already spent some thoughts on this 🙂

Completely agree we need some syntax to define custom blocks, and yes, the callout syntax is not...the most pretty :)

Mostly I'm trying to say I want to maintain both functionalities: A way to support stuff like auto-converting "Tip:" etc., and a neat way to create custom blocks (multi line tips still need to be wrapped as well anyway..).

This still seems fairly manual to me. I just want all of this automated away.

I am a bit torn on this one. Although I like automating this for content editors I am feeling a little uneasy on the aspect that any kind of injection magic might be unpredictable. That is why I liked registering used components from used template partials. But either the registration approach and the automatic one would work in both systems. Howsoever for which system we will settle I would love to implement the CSS bundle thing.

I do the automatic injection for imported reference docs and it's a real time saver. Works pretty well so far.

as we literally have a team working on building the best AMP editing experience for a CMS w/ WordPress.

Yep! Thought about this one as well but then remembered that we wanted to stick to a file-based solution especially to have a version controlled documentation. However using Wordpress would be a big step towards its community - saying that unbiased.

Yeah good point. Would be super cool if there was a way to use WordPress with a flat-file system..

Did you evaluate more CMS / site generators? Grav seems similarly small as Grow in terms of contributions and overall activity.

None as detailed as Grav though I gave Kirby https://getkirby.com/ (did not like: licensing, driven by a single person) and Automad https://automad.org/ (did not like: sadly litteraly only one contributor, custom template engine) a shot. Regarding PHP itself I think we are on the same page. Something I found beneficial though is that something like a amp-component-auto-injector written in PHP would benefit every AMP/PHP project.

Ok cool. I'm looking forward to hear Sebastian's and Raghu's thoughts.

Sorry that i took me so long to respond (I started twice, but couldn't come to an conclusion).

For me, the ideal solution would be a Node-based site generator:

Limits the used programming languages to JS, which has the advantage that everyone at Google who's working on AMP is familiar with it.
We don't have to mix different build systems.
Dev env setup becomes a lot easier.

And, the thing I'm mostly concerned about: how can we integrate the existing AMP by Example (ABE) compiler. What should we compile samples into? It might be an advantage being able to hook the ABE compiler directly into the respective site generator.

Having said that, I understand that there might not exist a site generator that fulfils all the needs of ampproject.org (in particular, I can't comment on the i18n requirements). And it might take a lot less effort to simply stick with Grow.

A few other notes:

Flat-file system is a must.
I'd prefer to stick to either JS, Python or Go.
Wordpress feels like it would add complexity at the wrong places (my experience might be a bit dated though).
I'm not sure component import injection magic is critical, removing unused imports could be a step performed by AMP Optimizer.

TLDR: I don't think Grav offers enough benefits, but I'd be happy to move away from Grow as well.

Thanks for your comment, @sebastianbenz! Actually you managed to express my gut feeling. 😅

We also did some research on JavaScript based SSGs of which there are some but sadly a lot of them make heavy assumptions about the used framework like for example Gatsby using React. Those that don't rely on frameworks (Metalsmith, eleventy, ...) then lack some features that are critical for amp.dev like i18n.

Then for now I'd suggest to stick with Grow but try to enhance the experience by using the learnings from our Grav adventure.

Sounds good to me! Thanks for the research, curious to see how we can improve the current workflow, and maybe we can revisit porting after launch in the future when the time is right.

jungvonmatt / amp.dev