Migrate GitLab Handbook from Middleman to Frontman

Problem to solve

TODO: This issue should be combined with or replace the Middleman epic, and have individual sub-issues created for the tasks identified below).

Middleman is the static site generator that powers all of about.gitlab.com, including the GitLab Handbook. At the scale we have achieved, we are running into numerous issue related to performance and collaboration. Frontman is a project started by Algolia in response to the exact problems we face.

Algolia's team has granted us alpha access to Frontman and we should evaluate the feasibility of implementing it as a drop-in replacement for Middleman.

• The gem: https://rubygems.org/gems/frontman-ssg
• The documentation: https://github.com/algolia/frontman/wiki
• The source code: https://github.com/algolia/frontman

Approach

• NOTE: We will not be converting the marketing site in the monorepo as part of this conversion. We will only convert the handbook site. The marketing website team is currently evaluating their tech stack needs and will establish which SSG they will use still.

1. Convert existing custom Middleman extensions to helper methods
2. Add monorepo support to Frontman
3. Complete decouple the handbook from the marketing site, by not sharing any assets NOTE: We will attempt to do the conversion without having a complete decoupling as a prerequisite.
4. Migrate the Handbook site from Middleman to Frontman

Identified Prerequisites and Tasks

• Add support for monorepo to Frontman
• Rename all helpers from *_helpers to *_helper. See https://github.com/algolia/frontman/wiki/Helper-methods#custom-helper-methods
• Need to switch build directory from public to default build, to avoid conflicts? See #8204 (closed)
• Convert asset pipeline: https://github.com/algolia/frontman/wiki/External-assets-pipeline
  • NOTE: Some or all of this necessary work may be done as part of the Growth Marketing groups Webpack conversion epic: https://gitlab.com/groups/gitlab-com/marketing/growth-marketing/-/epics/143
  • Try generating a new site with webpack template to see what it looks like as an example.
  • Use that and the existing Marketing site webpack config as an example, and convert all existing asset handling to webpack
  • Also get rid of Rollup and convert to webpack at the same time.
• Ensure that sitemap still works correctly

Testing and Acceptance Criteria

• Dev and build modes works for handbook and marketing sites
• All stylesheets work for handbook and marketing sites
• All javascripts work for handbook and marketing sites