User:JDrewniak (WMF)/notes/Style Guide SSG

= Style Guide Static Site Generators (or, SGSSG) = 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.

Maintainability

 * 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

 * 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

 * 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 = 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.