Style Guide Static Site Generators (or, SGSSG)[edit]

In ⚓ T164449 many suggestions were made on which static site generator to use for the Wikimedia Styleguide. The main reasons for moving the Styleguide to an SSG from static HTML is:

Enabling easier content editing for style-guide authors
Translating the styleguide into multiple languages
Using HTML templates to reduce duplication of code
Making it easier for others to use the Styleguide as a template for micro-sites

The reasons for not choosing MediaWiki as a CMS is the lack of flexibility when it comes to layouts, styling and mobile/responsive support. Using just basic HTML/CSS/JS gives us the ability to change the styleguide without the hinderances of any particular CMS. The goal of adding a SSG is to maintain that flexibility while making it easier for less-technical authors to contribute content.

Proposed SSG’s[edit]

Name	Language	i18n support	File format
Middleman	Ruby	Yes (falls back to the default language if there are no strings for the language it is looking for)	YAML or many others …even wiki markup (o_0)
Hexo	Node.js	Only for layout, not for source, which is not helpful to us (not sure about this, could someone test and update the task?). Couldn’t get it to work though.	JSON or YAML
Webpack build (html-loader, i18n-webpack-plugin)	Node.js	Yes (no fallbacks, I am guessing this does a simple replace)	JSON
Pelican	Python	i18n for source (page content); may be able to translate UI via Jinja-templates+passed parameter	YAML/Markdown/reStructuredText
Hugo	Go	Yes (uses go-18n)	Markdown and Org-mode
Jekyll	Ruby	With plugins: polyglot or jekyll-multiple-languages-plugin - note: not with gh-pages	Markdown
Gatsby	JavaScript	Yes. Content: with GraphQL query or with plugin. UI: jQuery.i18 bindings for React or any other React i18n plugin	Plugins for: Markdown, YAML, JSON, CSV, etc.

Evaluation Criteria[edit]

Maintainability[edit]

Does it use a broadly-applicable templating language? (ie. Mustache)
Does it use a well-known content language? ( ie. markdown, wikitext)
Does it require third-party plugins?
Does it require us to manually implement features?

All of the SSG’s suggested use Markdown as the content-input format. Markdown enables integration with services like prose.io, which enable online editing of markdown files in a user-friendly fashion. Due to resource considerations, we would like to go with a solution that doesn’t require a large engineering commitment and has an existing developer community. Given this creteria, a custom webpack build would not be desireable due to the high maintenance cost and high concentration of knowledge in a few individuals. Gatsy, also being highly configurable, requires features like menus and translations to be implemented manually, which increases maintenance cost.

Portability[edit]

Does it have a concept of “themes” or “skins”?
Does it enable the styleguide to be used as a template for other sites?

The concept of a “theme” or “skin” for the style-guide is desirable because it allows us to re-use the style-guide styles & components across other micro-sites. The ability to update a style-guide theme and have those changes propogate to other sites would also be desireable. The SSG’s that offer “themes” or “skins” are:

Hexo - theme docs
Hugo - theme docs
Pelican - theme docs
Jekyll - theme docs

Middleman offers “project templates” through it’s CLI.

Internationalization[edit]

Does it have a translation mechanism baked in?
Can it be integrated with translatewiki?

Multilinguage capabilities are a high priority for the style guide. Unfortunetly, this is where many SSG’s fall short of expectations.

Middleman - offers content and UI translation abilities, however, creating a lanuage-picker is surprisingly complicated and support for linking to other page is the current language is still missing.
Pelican - requires a plugin for multilinguage sites (last major update, 4 years ago).
Jekyll - also requires a plugin.

From all the SSG’s suggested, only Hugo has built-in support for advanced Internationalization, including:

“multilingual mode” which enables navigating an entire site in a given language (all links get converted to the current language).
built-in language-switcher.
Translation for menu-items, UI elements, as well as content.

Recommendation[edit]

Based on the factors listed above, I believe Hugo to be the best choice for an SSG for the style guide. Hugo has the best built-in i18n support, as well as a very powerful theme system. A theme in Hugo is just a Hugo website, placed inside another Hugo website. This is a very powerful system because it allows the styleguide to be both a self-contained website as well as a template for other websites. Because themes are imported as a git submodule in Hugo, they can also be easily updated. On the down-side, Hugo has a larger ramp-up time for developers than other SSG’s, because it doesn’t use a well-known templating language such as Mustache. It uses Go templates instead.