Choice of Static Site generator for Floe and Fluid Project websites

[Colin Clark]

Hi Sachin,

Thanks for your detailed analysis. It will probably take some time for people to read through it and share their thoughts; there’s a lot of interesting material here to think through here.

From my perspective, one of the major criteria for choosing a technology like this within the Fluid community is our ability to easily and comfortably adapt it or make extensions to it. That means, for most of us, writing code in JavaScript. It will be significantly easier and more interesting if developers can use Infusion in tandem with the static site generator, rather than to have to pick up a new programming language such as Python or Go and new tools/frameworks as well.

I’d also like to encourage you to approach the issue from a broader architectural perspective. Rather than just thinking of this as a standalone tool to generate websites from markdown or templating languages, it’s worth considering how it might act as one component within a larger ecosystem of tools. A big part of what makes the Fluid community unique (and I hope to make this clearer when we redesign the site this summer) is that we always try to approach technologies critically, with an eye to how they could be reconceptualized in ways that give non-experts more creative agency. While it’s often tempting to compare technologies using easily quantifiable metrics (e.g. number of Github stars, number of plugins, etc.), I think it’s worth emphasizing the more typically underrepresented considerations—not just popularity, number of stars, or community size—and try to imagine how a tool like this might fit more holistically into a “weave” of different interrelated technologies and practices. How would someone who doesn’t know Github or Markdown create or update content for the site? Could they redesign aspects of the site if the wanted to? How would dynamic sources of data be integrated into the site?

If it helps at all, several of our recent websites—the new Inclusive Design Research Centre site, the Project We Count site, and the eco-op site—were all developed using 11ty and deployed on Netlify. It’s still a new tool for us, but we’ve got a growing number of developers who have experience with it (more so than Hugo or Jekyll or the others). Notably, the IDRC site uses Netlify CMS to support updates to the website using a (more or less) WYSIWYG editor. The We Count site uses a headless WordPress instance as a backend feed for the site; this allows for a more polished WYSIWYG experience for non-technical site editors, and allows us to add much more dynamic features to the website than a standalone static site generator could provide. While the Fluid and FLOE sites are probably more on the static side of things, ideally we want to choose a tool that we can use for lots of different kinds of sites, and build a body of knowledge and facility with it across projects.

We will be migrating away from Jenkins in the future, or at least significantly reducing our dependence on it. Ned and Giovanni have been considering alternatives to it via the use of Github Actions, Netlify, and potentially some of our own self-hosted tooling to support automated previews and deployments.

I hope this helps,

Colin

---
Colin Clark
Associate Director
Inclusive Design Research Centre, OCAD University
https://idrc.ocadu.ca

On May 6, 2020, at 9:15 AM, SACHIN CHOPRA <schopra at mt.iitr.ac.in<mailto:schopra at mt.iitr.ac.in>> wrote:

Follow up on the last mail. Here's a detailed analysis of those SSGs and my views regarding choice of HUGO as SSG.
Each Static Site Generator has its own pros and cons. The right choice is based on what technologies and frameworks the present fluid community are familiar with, what technologies are presently being used in other projects to maintain consistency. Moreover build speed considerations, community support, ease of understanding for new contributors, ordered file structure, plugin support base, and the needs of the website also play an important role in deciding the static site generator.


Deciding Points:


  *
Gatsby

  1.
It is framework dependent.
  2.
We currently do not need GraphQL and not everyone is well-rehearsed with React
  3.
Gatsby requires a good understanding of React for development. The closer we get to "apps" on the "content site to app spectrum" the more we'd want to consider one of the framework-based tools. Our project sites are though more “content-driven” in nature.
  4.
Good plugin base and well documentation are general factors that can be found in other SSGs too. Build times increase exponentially as files increase and everything has to be stored in RAM which tends to run out as reported by developers.
  5.
Each plugin that we use on a Gatsby site adds load to the site's overall performance. Sometimes we can fix the situation by properly configuring those plugins, but quite often we just have to limit their number for a site thus imposing a restriction.


  *
Hugo

  1.
It's easy to install the software. Hugo doesn't depend on administrative privileges, databases, runtimes, interpreters, or external libraries.
  2.
Sites built with Hugo can be deployed on S3, Github Pages, Dropbox, or any web host. Hugo is fast & powerful. It's written for speed and performance.
  3.
Great care has been taken to ensure that Hugo’s build-time is as short as possible. It takes milliseconds to build an entire site for most setups. Hugo is flexible and designed to work how we do. We can organize our content however we want with any URL structure.
  4.
We can declare our own content types and define our own metadata in YAML, TOML, or JSON.
  5.
Documentation and community support are sufficient enough to complete the project. Versioning can be realized by the usage of tags. There is an inbuilt provision for tag-specific pages.


  *
11ty

  1.
It provides a flexible file structure system thus we can migrate while we maintain our current file structure.
  2.
It supports multiple file extensions and not just markdown. It’s written in JS which is not going to lose support any time soon.
  3.
But it has its downsides which can’t be ignored. It has a small community, and thus help isn’t easily available. It provides a flexible directory structure, every page needs to have a front matter that specifies the template it needs to use. This process is automated in other SSGs like Hugo.
  4.
Versioning can be done by collections<https://www.11ty.dev/docs/collections> but it’s not as intuitive as HUGO tags i.e. no tag-specific pages.
  5.
Non-availability of enough documentation and less support from the community can act as a huge factor affecting the development of our project.
  6.
It has a meager plugin base consisting of only three official plugins. Plugins, if needed, need to be self-written which will increase the time required to complete the project, thus diverting attention from other important topics.
  7.
The positive points that 11ty puts forward like the use of multiple templating language support aren’t of much use to our project. Build times are slow and the template engine base isn’t strong.


  *
Jekyll

  1.
It is more like a file-based CMS, without all the complexity. Jekyll takes your content, renders Markdown and Liquid templates, and spits out a complete, static website ready to be served by Apache, Nginx or another web server.
  2.
Jekyll is the engine behind GitHub Pages, which you can use to host sites right from your GitHub repositories. Compatibility with gh-pages is the major reason why most of the developers choose Jekyll over Hugo. Fluid project and FLOE Project websites are to be hosted on private servers though and hence the factor of gh-pages integration becomes obsolete.
  3.
Jekyll has a strict file structure system and iterating over files in the _data folder causes problems due to restricted liquid templating.
  4.
For example, site.data.diectory_name will loop through all the files present there without any plugin available to customize the loop. This causes problems if there are other subdirectories in the directory_name folder.
  5.
On a brighter side, we can’t ignore the fact that Jekyll is readily compatible with the GH-pages. Github can automatically build Jekyll sites.

It's hard to choose between HUGO and Jekyll. Jekyll comes with gh-pages compatibility. If we host FLOE and Fluid on the GH-pages, any commit made to these repositories would be automatically built and thus there is no need for an automation server. This, however, comes with the downside of the strict file structure that Jekyll uses. All the content files will have to be stored in data and iterating through a few of them sometimes becomes impossible as site.data.directory takes into account all of the files present in the given directory. Hugo provides a much more flexible structure and better Go templating compared to Liquid, but it's not readily compatible with gh-pages i.e. we will need an automation server to automate the builds for every commit.

The choice of SSG between HUGO and Jekyll boils down to the fact if we want to get rid of using Jenkins as an automation server to cut down on overhead costs. If we can continue to use Jenkins for automating builds, then HUGO would be the best choice. If our priority is to go with something that can be deployed reliably and with minimal effort when it comes to adding new content, maintaining old posts, etc. we should go with HUGO. The final choice for SSG would be decided after discussing with the community and comparing various pros and cons of different SSGs and stated above.
The phase-wise distribution ahead would take HUGO as an example for describing the workflow. The workflow would be similar even if we decide not to go with HUGO.
Regards
Sachin



On Wed, May 6, 2020 at 6:21 PM SACHIN CHOPRA <schopra at mt.iitr.ac.in<mailto:schopra at mt.iitr.ac.in>> wrote:
Hello everyone,
I was looking at different options available for the choice of SSG for floe and fluid project websites. Here's a table showing the pros and cons of various options available.
All the other repositories under fluid-project are using Hugo as the SSG and using it would maintain consistency across different repositories. Moreover, the features provided by Hugo would help us in easily implementing different features on the websites.
It would be great if you could look at the table once and comment on which should be the best choice for the same.
Regards
Sachin


[https://lh4.googleusercontent.com/qyj6pnFlodxKw3q0bIljqlmIYjqi6Rm4WGxF1nb_zNwx-EOkmqUqbptnPNVKPxOthAOdJNp_OvHtVkZqccMEZajVZeZBd0txN-alXQkzJ1VZ34rgKarU3Sl_-J1CScmDf5oQ7r9L]
[https://lh5.googleusercontent.com/vFo3KnzOp0D5LhEjAGVO2rRlp0P2I9pmpC1JLQg8_B-yOh4uhykSA2bsN6Kc1LpPj0qzo5lq-C9nFqdsjK8MqkAl728FFenz8J_DxbrvFU_BUshKasAV2P1HXe7-Tw49VG5w-Js0]
  [https://lh3.googleusercontent.com/BhV-7msP5WICma2Pnjuti4s2StBz9mNq4KmbXDNnRmhwG-4CW8ZcypbOJJ8ysvYShC-tFa8aSqWkM3tx0a0a0ncGjZWeqjhHME7rLGVSDRZ_rN9FKQRPZv-wdXKkL6fxAbrp5Tab]
[https://lh6.googleusercontent.com/GO68OoXEv7r3HqBwF9Th7Y6pSIj6MSU4dUjoGaBS6MxfLFQ7guLD0Yt1GGXRMp8sxFtTlohhUn-NWEHeuMCOd0yD7anONKT8Jf-aYCreRjIUNIHRqKpIsM98i0ofhG4eIVVOs4SI]
Github Stars
42.7k 🌟
42.2k 🌟
39.9k🌟
4.6k🌟
Language
JavaScript
Go
Ruby
Javascript
Templates
React
Go
Liquid
Multiple support
Integration
React, Webpack, GraphQL
Markdown, GitLab Pages, Buddy
Gitlab Pages, Comment It, Github Pages
GH-pages, Markdown
Pros
Progressive Web Application is developed.
Faster to develop.

Built-in Development Server.
Supports multiple template languages.

Supports GraphQL
Don’t need time to figure out configurations.
SEO-conscious in nature.
Zero boilerplate client-side JavaScript.

Supports a huge ecosystem of Plugins.
Cross-Platform Availability
Good plugin and theme support base.
Zero Config: Works with the project’s default file structure.

Well written tutorial and documentation
Supports TOML, YAML, and JSON for the front matter and strong theme base
Liquid templating is convenient and easy to understand.
Written in JS, we can write our own plugins and data processing tools as per need.

Vast and active community. Help easily available.
Enterprise-ready. With support for multilingual sites
Readily integrable with Github pages.
zero-config by default but flexible conf. Options


[https://lh4.googleusercontent.com/qyj6pnFlodxKw3q0bIljqlmIYjqi6Rm4WGxF1nb_zNwx-EOkmqUqbptnPNVKPxOthAOdJNp_OvHtVkZqccMEZajVZeZBd0txN-alXQkzJ1VZ34rgKarU3Sl_-J1CScmDf5oQ7r9L]
[https://lh5.googleusercontent.com/vFo3KnzOp0D5LhEjAGVO2rRlp0P2I9pmpC1JLQg8_B-yOh4uhykSA2bsN6Kc1LpPj0qzo5lq-C9nFqdsjK8MqkAl728FFenz8J_DxbrvFU_BUshKasAV2P1HXe7-Tw49VG5w-Js0]
  [https://lh3.googleusercontent.com/BhV-7msP5WICma2Pnjuti4s2StBz9mNq4KmbXDNnRmhwG-4CW8ZcypbOJJ8ysvYShC-tFa8aSqWkM3tx0a0a0ncGjZWeqjhHME7rLGVSDRZ_rN9FKQRPZv-wdXKkL6fxAbrp5Tab]
  [https://lh6.googleusercontent.com/GO68OoXEv7r3HqBwF9Th7Y6pSIj6MSU4dUjoGaBS6MxfLFQ7guLD0Yt1GGXRMp8sxFtTlohhUn-NWEHeuMCOd0yD7anONKT8Jf-aYCreRjIUNIHRqKpIsM98i0ofhG4eIVVOs4SI]
Cons
Needs a strong understanding of ReactJS.
No Plugin support
No Image editor

Small community. Help isn’t easily available.

Beginners find it tough to develop.
Uses Go’s Template instead of Liquid which is non-user friendly.
Build time increases with the addition of plugins
Small Plugin support base. Only three official plugins are present.

Build time increases dramatically with files and styles
No asset pipeline.
Slower to build compared to Hugo.
Build times are slow compared to Hugo and Jekyll.

Everything has to be stored in memory and hence RAM tends to run out while building it.
No XML Support for data feeds.
Restricted file structure. Iterating through data files is limited in nature.
The template base isn’t strong, unlike Jekyll and Hugo.
Recommendation
Not suitable as per our needs.
Candidate for further evaluation.
Candidate for further evaluation.
Too small/poorly adopted to consider.


_______________________________________________________
fluid-work mailing list - fluid-work at lists.idrc.ocad.ca<mailto:fluid-work at lists.idrc.ocad.ca>
To unsubscribe, change settings or access archives,
see https://lists.idrc.ocad.ca/mailman/listinfo/fluid-work

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200506/f7e0549a/attachment.htm>