Migrate docs to Vuepress (#442)

* first pass

* fix up homepage

* more work

* housekeeping

* add script to modify home link

* add check docs

* build docs site

* Create CNAME

* fix path to check-docs

* update from template

* fix logo in readme

* fix link

* remove logspam

* remove old folders

* fix all links

* fix up readme

* change up Insights description

* add customization docs

* phrasing

* title

* titles

* titles

* change webhook docs

* refresh template

* rebuild site

* refresh from template repo

* phrasing

* add tagline

* update readme\, add readme sync script

* fix logo

* rebuild

* fix readme script

* rebuild

.github/workflows/build-site.yml

@@ -0,0 +1,44 @@
+# This file is generated from FairwindsOps/documentation-template
+# DO NOT EDIT MANUALLY
+
+name: Build Website
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: cd docs-md
+    - run: npm ci
+    - run: npm run check-links
+    - run: |
+        username="GitHub Actions"
+        git config user.email "opensource@fairwinds.com"
+        git config user.name $username
+        npm run build
+        HAS_CHANGE=$(git diff .)
+        if [ -n "${HAS_CHANGE}" ]; then
+          if [ "$(git log -1 --pretty=format:'%an')" == $username ]; then
+            echo "Build created a diff, but the last commit was a build."
+            exit 1
+          fi
+          git add docs/
+          git commit -m "[CI] rebuild website"
+          git push
+        fi
+    env:
+        CI: true

.gitignore

@@ -24,3 +24,5 @@ dist
 .vscode
 
 *-test.yaml
+
+node_modules

README.md

@@ -1,93 +1,58 @@
-<div align="center">
-  <img src="/img/polaris-logo.png" alt="Polaris Logo" />
+<div align="center" class="no-border">
+  <img src="https://polaris.docs.fairwinds.com/img/polaris-logo.png" alt="Polaris Logo">
   <br>
-
-  [![Version][version-image]][version-link] [![CircleCI][circleci-image]][circleci-link] [![Go Report Card][goreport-image]][goreport-link]
+  <h3>Best Practices for Kubernetes Workload Configuration</h3>
+  <a href="https://github.com/FairwindsOps/polaris">
+    <img src="https://img.shields.io/static/v1.svg?label=Version&message=1.2.0&color=239922">
+  </a>
+  <a href="https://goreportcard.com/report/github.com/FairwindsOps/polaris">
+    <img src="https://goreportcard.com/badge/github.com/FairwindsOps/polaris">
+  </a>
+  <a href="https://circleci.com/gh/FairwindsOps/polaris.svg">
+    <img src="https://circleci.com/gh/FairwindsOps/polaris.svg?style=svg">
+  </a>
 </div>
 
-[version-image]: https://img.shields.io/static/v1.svg?label=Version&message=1.2.0&color=239922
-[version-link]: https://github.com/FairwindsOps/polaris
-
-[goreport-image]: https://goreportcard.com/badge/github.com/FairwindsOps/polaris
-[goreport-link]: https://goreportcard.com/report/github.com/FairwindsOps/polaris
-
-[circleci-image]: https://circleci.com/gh/FairwindsOps/polaris.svg?style=svg
-[circleci-link]: https://circleci.com/gh/FairwindsOps/polaris.svg
-
 Fairwinds' Polaris keeps your clusters sailing smoothly. It runs a variety of checks to ensure that
 Kubernetes pods and controllers are configured using best practices, helping you avoid
 problems in the future. Polaris can be run in a few different modes:
 
 Polaris can be run in three different modes:
-* As a [dashboard](#dashboard), so you can audit what's running inside your cluster.
-* As a [validating webhook](#webhook), so you can automatically reject workloads that don't adhere to your organization's policies.
-* As a [command-line tool](#cli), so you can test local YAML files, e.g. as part of a CI/CD process.
+* As a [dashboard](https://polaris.docs.fairwinds.com/dashboard), so you can audit what's running inside your cluster.
+* As an [admission controller](https://polaris.docs.fairwinds.com/admission-controller), so you can automatically reject workloads that don't adhere to your organization's policies.
+* As a [command-line tool](https://polaris.docs.fairwinds.com/infrastructure-as-code), so you can test local YAML files, e.g. as part of a CI/CD process.
 
 **Want to learn more?** Reach out on [the Slack channel](https://fairwindscommunity.slack.com/messages/polaris) ([request invite](https://join.slack.com/t/fairwindscommunity/shared_invite/zt-e3c6vj4l-3lIH6dvKqzWII5fSSFDi1g)), send an email to `opensource@fairwinds.com`, or join us for [office hours on Zoom](https://fairwindscommunity.slack.com/messages/office-hours)
 
----
-
-**Get more from Polaris** with [Fairwinds Insights](https://www.fairwinds.com/insights?utm_campaign=Hosted%20Polaris%20&utm_source=polaris&utm_term=polaris&utm_content=polaris) -
-Insights can help you track Polaris findings over time, send new findings to Slack and Datadog, and integrate other
-Kubernetes auditing tools such as
-[Trivy](https://github.com/aquasecurity/trivy) and [Goldilocks](https://github.com/FairwindsOps/goldilocks/)
 
----
+## Documentation
+Check out the [documentation at docs.fairwinds.com](https://polaris.docs.fairwinds.com)
 
-# Dashboard Quickstart
+## Integration with Fairwinds Insights
+[Fairwinds Insights](https://www.fairwinds.com/insights?utm_campaign=Hosted%20Polaris%20&utm_source=polaris&utm_term=polaris&utm_content=polaris)
+is a platform for auditing Kubernetes clusters and enforcing policy. If you'd like to:
+* manage Polaris across a fleet of clusters
+* track findings over time
+* send results to services like Slack and Datadog
+* add additional checks from tools like
+[Trivy](https://github.com/aquasecurity/trivy),
+[Goldilocks](https://github.com/FairwindsOps/goldilocks/), and
+[OPA](https://www.openpolicyagent.org)
 
-```bash
-kubectl apply -f https://github.com/FairwindsOps/polaris/releases/latest/download/dashboard.yaml
-kubectl port-forward --namespace polaris svc/polaris-dashboard 8080:80
-```
-With the port forwarding in place, you can open http://localhost:8080 in your browser to view the dashboard.
+you can sign up for a [free account here](https://insights.fairwinds.com?source=polaris).
 
-* * *
+## Contributing
+PRs welcome! Check out the [Contributing Guidelines](https://polaris.docs.fairwinds.com/contributing/) and [Code of Conduct](https://polaris.docs.fairwinds.com/code-of-conduct) for more information.
 
-# Components
+## Further Information
+A history of changes to this project can be viewed in the [Changelog](https://polaris.docs.fairwinds.com/changelog/)
 
-## Dashboard
-> [View installation instructions](docs/usage.md#dashboard)
+If you'd like to learn more about Polaris, or if you'd like to speak with
+a Kubernetes expert, you can contact `info@fairwinds.com` or [visit our website](https://fairwinds.com)
 
-The Polaris dashboard is a way to get a simple visual overview of the current state of your Kubernetes workloads as well as a roadmap for what can be improved. The dashboard provides a cluster wide overview as well as breaking out results by category, namespace, and workload.
+---
 
 <p align="center">
-  <img src="/img/dashboard-screenshot.png" alt="Polaris Dashboard" width="550"/>
+  <img src="https://polaris.docs.fairwinds.com/img/dashboard-screenshot.png" alt="Polaris Dashboard" width="550"/>
 </p>
 
-Our default standards in Polaris are rather high, so don’t be surprised if your score is lower than you might expect. A key goal for Polaris was to set a high standard and aim for great configuration by default. If the defaults we’ve included are too strict, it’s easy to adjust the configuration as part of the deployment configuration to better suit your workloads.
-
-
-## Admission Controller: Validating Webhook
-> [View installation instructions](docs/usage.md#webhook)
-
-Polaris can be run as an admission controller that acts as a validating webhook. This accepts the same configuration as the dashboard, and can run the same validations. This webhook will reject any workloads that trigger a danger-level check. This is indicative of the greater goal of Polaris, not just to encourage better configuration through dashboard visibility, but to actually enforce it with this webhook. Polaris will not fix your workloads, only block them. 
-
-The webhook only supports a fixed set of controller types. You can see the
-[list of supported controllers here](https://github.com/FairwindsOps/polaris/blob/master/cmd/polaris/webhook.go#L40)
-
-Unfortunately we have not found a way to display warnings as part of `kubectl` output unless we are rejecting a workload altogether. That means that any checks with a severity of `warning` will still pass webhook validation, and the only evidence of that warning will either be in the Polaris dashboard or the Polaris webhook logs.
-
-## CLI
-> [View installation instructions](docs/usage.md#cli)
-
-Polaris can also be used on the command line, either to audit local files or a running cluster.
-This is particularly helpful for running Polaris against your infrastructure-as-code as part of a
-CI/CD pipeline. Use the available [command line flags](docs/usage.md#running-with-ci-cd)
-to cause CI/CD to fail if your Polaris score drops below a certain threshold, or if any danger-level issues arise.
-
-# Installation and Usage
-See the [Usage Guide](/docs/usage.md) for details on different methods for installing and using Polaris.
-
-# Contributing
-PRs welcome! Check out the [Contributing Guidelines](CONTRIBUTING.md),
-[Code of Conduct](CODE_OF_CONDUCT.md), and [Roadmap](ROADMAP.md) for more information.
-
-# Further Information
-A history of changes to this project can be viewed in the [Changelog](CHANGELOG.md)
-
-If you'd like to learn more about Polaris, or if you'd like to speak with
-a Kubernetes expert, you can contact `info@fairwinds.com` or [visit our website](https://fairwinds.com)
-
-# License
-Apache License 2.0

docs-md/.vuepress/config-extras.js

@@ -0,0 +1,58 @@
+module.exports = {
+  title: "Fairwinds Polaris Documentation",
+  description: "Documentation for Fairwinds Polaris - audit and enforce Kubernetes best practices for your workloads",
+  themeConfig: {
+    docsRepo: "FairwindsOps/polaris",
+    sidebar: [
+      {
+        title: "Polaris",
+        path: "/",
+        sidebarDepth: 0,
+        collapsable: false,
+        children: [
+          {
+            title: "Changelog",
+            path: "/changelog",
+          },
+          {
+            title: "Code of Conduct",
+            path: "/code-of-conduct",
+          },
+          {
+            title: "Contributing",
+            path: "/contributing",
+          },
+        ],
+      },
+      {
+        title: "Ways to Run Polaris",
+        collapsable: false,
+        children: [
+          "/dashboard",
+          "/admission-controller",
+          "/infrastructure-as-code",
+        ],
+      },
+      {
+        title: "Customization",
+        collapsable: false,
+        children: [
+          "/customization/configuration",
+          "/customization/checks",
+          "/customization/custom-checks",
+          "/customization/exemptions",
+        ]
+      },
+      {
+        title: "Checks",
+        collapsable: false,
+        sidebarDepth: 0,
+        children: [
+          "/checks/security",
+          "/checks/efficiency",
+          "/checks/reliability",
+        ],
+      },
+    ]
+  }
+}

docs-md/.vuepress/config.js

@@ -0,0 +1,73 @@
+// This file is generated from FairwindsOps/documentation-template
+// DO NOT EDIT MANUALLY
+
+const fs = require('fs');
+const npath = require('path');
+
+const CONFIG_FILE = npath.join(__dirname, 'config-extras.js');
+const BASE_DIR = npath.join(__dirname, '..');
+
+const extras = require(CONFIG_FILE);
+if (!extras.title || !extras.description || !extras.themeConfig.docsRepo) {
+  throw new Error("Please specify 'title', 'description', and 'themeConfig.docsRepo' in config-extras.js");
+}
+
+const docFiles = fs.readdirSync(BASE_DIR)
+  .filter(f => f !== "README.md")
+  .filter(f => f !== ".vuepress")
+  .filter(f => f !== "node_modules")
+  .filter(f => npath.extname(f) === '.md' || npath.extname(f) === '');
+
+const sidebar = [['/', 'Home']].concat(docFiles.map(f => {
+  const ext = npath.extname(f);
+  if (ext === '') {
+    // this is a directory
+    const title = f;
+    const children = fs.readdirSync(npath.join(BASE_DIR, f)).map(subf => {
+      return '/' + f + '/' + npath.basename(subf);
+    });
+    return {title, children};
+  }
+  const path = npath.basename(f);
+  return path;
+}));
+
+const baseConfig = {
+  title: "",
+  description: "",
+  head: [
+    ['link', { rel: 'icon', href: '/favicon.png' }],
+    ['script', { src: '/scripts/modify.js' }],
+    ['script', { src: '/scripts/leadlander.js' }],
+  ],
+  themeConfig: {
+    docsRepo: "",
+    docsDir: 'docs-md',
+    editLinks: true,
+    editLinkText: "Help us improve this page",
+    logo: '/img/fairwinds-logo.svg',
+    heroText: "",
+    sidebar,
+    nav: [
+      {text: 'View on GitHub', link: 'https://github.com/' + extras.themeConfig.docsRepo},
+    ],
+  },
+  plugins: {
+    'vuepress-plugin-clean-urls': {
+      normalSuffix: '/',
+      notFoundPath: '/404.html',
+    },
+    'check-md': {},
+  },
+}
+
+let config = JSON.parse(JSON.stringify(baseConfig))
+if (!fs.existsSync(CONFIG_FILE)) {
+  throw new Error("Please add config-extras.js to specify your project details");
+}
+for (let key in extras) {
+  if (!config[key]) config[key] = extras[key];
+  else if (key === 'head') config[key] = config[key].concat(extras[key]);
+  else Object.assign(config[key], extras[key]);
+}
+module.exports = config;

docs-md/.vuepress/public/scripts/leadlander.js

@@ -0,0 +1,12 @@
+/*
+ * This file is generated from FairwindsOps/documentation-template
+ * DO NOT EDIT MANUALLY
+ */
+
+var llcookieless = true;
+var sf14gv = 32793;
+(function() {
+  var sf14g = document.createElement('script');
+  sf14g.src = 'https://lltrck.com/lt-v2.min.js';
+  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(sf14g, s);
+})();

docs-md/.vuepress/public/scripts/modify.js

@@ -0,0 +1,15 @@
+/*
+ * This file is generated from FairwindsOps/documentation-template
+ * DO NOT EDIT MANUALLY
+ */
+
+document.addEventListener("DOMContentLoaded", function(){
+  setTimeout(function() {
+    var link = document.getElementsByClassName('home-link')[0];
+    linkClone = link.cloneNode(true);
+    linkClone.href = "https://fairwinds.com";
+    link.setAttribute('target', '_blank');
+    link.parentNode.replaceChild(linkClone, link);
+  }, 1000);
+});
+