MediaWiki

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

< User:JDrewniak (WMF) | notes

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:

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.

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.

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:JDrewniak_(WMF)/notes/Style_Guide_SSG&oldid=2763927"