VuePress PoC

[mitovskaol]

Platform Services Team is looking for a product that can replace DevHub as a content management system for technical docs that are stored in DevHub. The CMS should meet the requirements outlined in this ticket

We like the tech docs site that UK gov built and ideally want something very similar.

Additional consideration: We plan to use WordPress for our "business" website so would be good to know if VuePress can or cannot integrate with WordPress.

Note: Cloud Pathfinder ran a PoC to test VuePress with the Openshift 101 content. See the results here.
DoD:

• [x] have a VuePress installed in a ee74a4-dev in KLAB locally and assess how it meets the requirements above.
• [x] Assess if the VuePress site can be integrated with KeyCloak SSO for user authentication as per this article If it can, we will be able to retire Documize and have one doc location!
• [x] Document the assessment results in this ticket and present at a Team Huddle

[mitovskaol]

@juhewitt ^^^

[ty2k]

Here are my research findings for how Vuepress might act to replace devhub-app-web:

Vuepress is a static site generator that uses the Vue.js front-end framework to build a site from a series of Markdown documents. It includes options for customizing look and feel through configuration options and plugins. It is commonly used for documentation sites in a monorepo format, where all of the target documents are kept right in the repository alongside the Vuepress configuration.

Looking at the DevHub Ecosystem Diagram, Vuepress is a candidate for replacing the "DevHub App Frontend" block, where Gatsby now resides:

Gatsby has very similar features to Vuepress, but it uses the React front-end framework rather than Vue.

In terms of individual requirements for a DevHub replacement:

GitHub integration and ability to pull content from multiple repos

Much like we are using DevHub now, we would have to add the functionality to pull from multiple repos ourselves if we were to swap Gatsby out for Vuepress. This requirement is a complicating factor for any CMS solution, as it's not a standard pattern for documentation sites built using static site generators. The more common monorepo approach means a merged pull request in the repository kicks off a new build automatically.

To support content freshness across multiple repos, we could:

• Use a scheduled cronjob to regularly re-build the app with up to date content (we do this now with DevHub). This approach doesn't give us automatic/instant updates when a source repo gets updated.
• Add custom logic to watch for updates on disparate GitHub repositories. Ideally, this could happen through some kind of push notification from GitHub, which could kick off an automatic update.
• Do something else.

Searchability - robust search engine

Vuepress includes a simple search, but it only indexes document titles, H2 and H3 tags, and tags added in Markdown front matter (source). The Vuepress docs specifically mention Algolia as a solution for full text search.

Robust search is another feature we would have to build ourselves, as we've done with our Algolia integration in DevHub now.

Easy to use interface to organizing content and the layout

Vuepress and Gatsby are equally capable of this. It will be up to us to decide on layout and content organization using either framework. The left hand ordered list navigation from Vuepress or GOV.UK Developer Docs can be accomplished with either site generator.

WordPress integration

There isn't a built-in integration available. WordPress does have a REST API that could be accessed from a static site created by Vuepress or Gatsby. It would be necessary to build this ourselves for whatever static site generator we are using.

Keycloak SSO integration

No built-in integration exists. Similar to the Keycloak integration that has been added to DevHub, we would be building this ourselves. Because Vuepress controls the application routing, an integration like the one linked in the ticket (Authenticating Vuepress Apps with Auth0) would be used for hiding blocks of content within a page that any user can access, as opposed to redirecting non-authenticated users to a login page as you would expect (like with Documize now).

Overall impressions

Swapping out Gatsby for Vuepress within our DevHub application would be a lateral move that doesn't give us clear benefits. Given the size of our dev team, we would want to carefully decide whether we should introduce Vue or Angular front-end dependencies in our stacks. These frameworks are great, but having to switch between frameworks when moving from app to app could slow us down and limit code re-use.

For any DevHub replacement, we should carefully weigh the requirements for supporting multiple repositories and for public and private content on the same site. For example, if we ended up with two simple static sites, one totally public (public repo and public site content) and one totally private (private repo and public site with all routes behind authentication), we could potentially end up with much easier maintenance and fresher documentation (due to lower barriers to contribution).