Create separate documentation site

[garethr]

As we both add more features, more examples and more integrations (Helm, GitHub Actions, etc.) the README won't be the best place to put all the documentation.

It would be good to create a separate docs site with multiple pages.

I've had good luck with MkDocs (https://www.mkdocs.org/) before, for instance with https://github.com/instrumenta/kubeval. This just involves a simple config file and a directory of markdown files managed in the same repo.

[jpreese]

I would love to try Hugo with the Learn theme (https://themes.gohugo.io/hugo-theme-learn/) and Netlify (https://www.netlify.com/)

The Netlify integration actually deploys your PR to a staging environment (e.g. PR#-conftest.staging.url.com) so you can see what it will do without having to do. Making it easier for contributors who just want to directly edit the markdown from GitHub as well as reviewers of PRs.

You can see a working example of this from the Athens repository (https://github.com/gomods/athens/pull/1340)

[kmcquade]

+1 on Hugo and Netlify.

I'd chip in as well.

[Blokje5]

@garethr @jpreese @boranx I see more need for this at the moment. A lot of questions on the OPA Slack show that we could really improve our documentation.

My proposal is the following:

• We start with a docs folder with seperate documentation (I already did this for the plugin feature). This folder contains markdown files for each relevant topic.
• We create a certain folder structure in the docs folder, e.g. something like this:

  /commands
  /rego
  /examples
  /plugin
  /...

  This means we already have some structured documentation.

• After some initial docs have been written we can look at the creation of a new documentation site.

[garethr]

I grabbed some time and converted the existing README over into separate files in the docs folder, and I've configured Mkdocs to generate a site. I can get this up on [conftest.dev]() once #263 is merged.