Skip to content

docs: Review documentation site generation for versioned OPA docs #7037

Open
@charlieegan3

Description

@charlieegan3

Currently we use Hugo to build a website for OPA's homepage and documentation content. There are some sharp edges in this setup:

  • developers must use a compatible Hugo version, 0.113.0. It's not currently possible for us to upgrade without updating the old content due to the use of a front matter field.
  • there are two content dirs, one containing the regular Hugo content under website and another containing the current docs content. Running generation scripts is required to be able to build a local version of the site for testing docs changes.
  • Versioned docs are generated by copying the docs content from all versions into a generated content dir under docs. This generates paths the like /docs/v0.67.1/. The challenge that this poses is that content from past versions of OPA must work with the current Hugo site and configuration. This is something which, if broken, is only spotted after merging to main when all the contents is updated.

These issues make it hard to maintain the docs, and, I feel, place the bar to drive by docs contributions too high.

I think we should consider a system where:

  • all content from all versions is easily available when developing the site, rather than needing to run lots of generation scripts and pull state from git.
  • Use a static site generator which has native versioned docs support.
  • Review the content where versioning is important, the note from https://docusaurus.io/docs/versioning is interesting:

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

What if we only versioned a limited set of pages, for example:

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions