[docs] render the documentation as a website

.gitignore

@@ -63,3 +63,15 @@ testoutput.txt
 ./certs/
 commit_logs
 bootstrap.yaml
+
+# hugo static site generator
+.DS_Store
+.sass-cache/
+.yarnclean
+.publish/*
+.publish/
+public/*
+docs/public/*
+node_modules/
+vendor/
+rootfs/

docs/README.md

@@ -0,0 +1,94 @@
+A documentation website for the [OSM](https://github.com/openservicemesh/osm/) project - [docs.openservicemesh.io](https://docs.openservicemesh.io)
+
+# Editing Content
+
+docs.openservicemesh.io is a static site. The documentation content needs to be located at `docs/content/docs/`.
+
+To ensure the docs content renders correctly in the theme, each page will need to have [front matter](https://gohugo.io/content-management/front-matter/) metadata. Example front matter:
+
+```
+---
+title: "Docs Home"
+linkTitle: "Home"
+description: "OSM Docs Home"
+weight: 1
+type: docs
+---
+```
+
+## Front Matter Notes:
+
+* inclusion of `type: docs` is important for the theme to properly index the site contents
+* the `linkTitle` attribute allows you to simplify the name as it appears in the left-side nav bar - ideally it should be short and clear - whereas the title can handle longform names for pages/documents.
+
+## Versioning the Docs Site
+
+When a new OSM release is cut, the docs site should be updated to reflect the version change. The underlying Docsy theme has versioning support built-in.
+
+<img width="244" alt="Screen Shot 2020-10-27 at 11 25 23 AM" src="https://user-images.githubusercontent.com/686194/97345732-a979ab80-1847-11eb-8c42-1b52c422a722.png">
+
+## Release and Versioning Process:
+
+1. Create an archive of the current `main` branch, following the naming convention used by [prior releases](https://github.com/openservicemesh/osm/branches). Push this archival branch to `upstream`.
+
+<img width="301" alt="Screen Shot 2020-10-27 at 11 11 17 AM" src="https://user-images.githubusercontent.com/686194/97343954-5999e500-1845-11eb-96f4-d9d59352a830.png">
+
+2. Once a release version branch is pushed to `upstream`, Netlify will build and deploy the documentation found within that branch. Within a couple of minutes of the branch push, the version of the site should be accessible at `https://<BRANCHNAME>--osm-docs.netlify.app/`
+
+Test the url for the branch once deployed to ensure it is working.
+
+3. Update the site version menu to reflect the changes
+
+<img width="723" alt="Screen Shot 2020-10-27 at 11 36 02 AM" src="https://user-images.githubusercontent.com/686194/97346387-9ca98780-1848-11eb-8179-523dcbed79c0.png">
+
+The version dropdown menu in set in the sites' `config.toml` (L73) file - adding a new `params.versions` archival entry for the prior release/branch, using the url from Netlify. The current release at the top of the list should reflect (i) the new version and (ii) the primary docs website url.
+
+Example _(where v5 is new and v4 is now an archival prior release):_
+
+```
+[[params.versions]]
+  version = "v0.5"
+  url = "https://docs.openservicemesh.io"
+
+[[params.versions]]
+  version = "v0.4"
+  url = "https://release-v0.4--osm-docs.netlify.app"
+```
+
+See [the Doscy versioning docs](https://www.docsy.dev/docs/adding-content/versioning/) for more information on these theme config parameters.
+
+> Note: the versioning controls are forward-facing only due to the nature of git branch history. The documentation website and netlify build process was added after `release-v0.4`, so only future releases will be deployed in this manner. The first release to be properly archived in this way will be `release-v0.5`. Trying to access archival urls for earlier versions (0.1 to 0.4) will not work because they predate this documentation website.
+
+
+
+# Site Development
+
+## Notes
+
+* built with the [Hugo](https://gohugo.io/) static site generator
+* custom theme uses [Docsy](https://www.docsy.dev/) as a base, with [Bootstrap](https://getbootstrap.com/) as the underlying css framework and some [OSM custom sass](https://github.com/openservicemesh/osm/pull/1840/files#diff-374e78d353e95d66afe7e6c3e13de4aab370ffb117f32aeac519b15c2cbd057aR1)
+* deployed to [Netlify](https://app.netlify.com/sites/osm-docs/deploys) via merges to master. (@flynnduism can grant additional access to account)
+* metrics tracked via Google Analytics
+
+## Install dependencies:
+
+* Hugo [installation guide](https://gohugo.io/getting-started/installing/)
+* packages are installed by running `yarn`
+
+## Run the site:
+
+```
+// rebuild the site (to compile latest css/js)
+hugo
+
+// or serve the site for local dev
+hugo serve
+```
+
+## Deploying the site:
+
+The site auto deploys the master branch via [Netlify](https://app.netlify.com/sites/osm-docs). Once pull requests are merged the changes will appear at docs.openservicemesh.io after a couple of minutes. Check the [logs](https://app.netlify.com/sites/osm-docs/deploys) for details.
+
+[![Netlify Status](https://api.netlify.com/api/v1/badges/8c8b7b52-b87f-42e0-949a-a784c3ca6d9a/deploy-status)](https://app.netlify.com/sites/osm-docs/deploys)
+
+`hugo serve` will run the site locally at [localhost:1313](http://localhost:1313/)

docs/archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+

docs/config.toml

@@ -0,0 +1,94 @@
+title = "Open Service Mesh"
+baseURL = "https://docs.openservicemesh.io/"
+languageCode = "en-us"
+description = "Documentation for Open Service Mesh (OSM)"
+theme = "dosmy"
+
+# Theme General Config
+[languages]
+[languages.en]
+title = "Open Service Mesh"
+description = "Documentation for Open Service Mesh (OSM)"
+languageName ="English"
+weight = 1
+[services]
+[services.googleAnalytics]
+id = "UA-130516746-13"
+enableRobotsTXT = true
+enableGitInfo = true
+contentDir = "content"
+version_menu = "Releases"
+defaultContentLanguage = "en"
+defaultContentLanguageInSubdir = false
+enableMissingTranslationPlaceholders = true
+disableKinds = ["taxonomy", "taxonomyTerm"]
+pygmentsCodeFences = true
+pygmentsUseClasses = false
+pygmentsUseClassic = false
+pygmentsStyle = "tango"
+[imaging]
+resampleFilter = "CatmullRom"
+quality = 75
+anchor = "smart"
+[blackfriday]
+plainIDAnchors = true
+hrefTargetBlank = true
+angledQuotes = false
+latexDashes = true
+[markup]
+  [markup.goldmark]
+    [markup.goldmark.renderer]
+      unsafe = true
+  [markup.highlight]
+      style = "tango"
+
+
+# OSM top menu (should match main site)
+[[menu.main]]
+	name = "Home"
+	weight = 10
+	url = "https://openservicemesh.io"
+[[menu.main]]
+	name = "Docs"
+	weight = 20
+	url = "/docs"
+[[menu.main]]
+	name = "Github"
+	weight = 30
+	url = "https://github.com/openservicemesh/osm"
+[[menu.main]]
+	name = "Blog"
+	weight = 40
+	url = "https://openservicemesh.io/blog"
+[[menu.main]]
+	name = "Slack"
+	weight = 50
+	url = "https://cloud-native.slack.com/archives/C018794NV1C"
+[[menu.main]]
+	name = "Twitter"
+	weight = 60
+	url = "https://twitter.com/openservicemesh"
+
+
+# Add your release versions here
+[[params.versions]]
+  version = "v0.4"
+  url = "https://docs.openservicemesh.io"
+
+
+# Theme Additional params
+[params]
+copyright = "The Docsy Authors"
+offlineSearch = true
+prism_syntax_highlighting = true
+
+[params.ui]
+navbar_logo = true
+sidebar_menu_compact = false
+breadcrumb_disable = false
+sidebar_search_disable = false
+
+[params.ui.feedback]
+enable = true
+yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
+no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'

docs/content/_index.md

@@ -0,0 +1,46 @@
+---
+title: "Docs Home"
+description: "OSM Docs Home"
+type: docs
+---
+
+## Overview
+
+OSM runs an Envoy based control plane on Kubernetes, can be configured with SMI APIs, and works by injecting an Envoy proxy as a sidecar container next to each instance of your application. The proxy contains and executes rules around access control policies, implements routing configuration, and captures metrics. The control plane continually configures proxies to ensure policies and routing rules are up to date and ensures proxies are healthy.
+
+## Core Principles
+* Simple to understand and contribute to
+* Effortless to install, maintain, and operate
+* Painless to troubleshoot
+* Easy to configure via Service Mesh Interface (SMI)
+
+## Features
+* Easily and transparently configure traffic shifting for deployments
+* Secure service to service communication by enabling mTLS
+* Define and execute fine grained access control policies for services
+* Observability and insights into application metrics for debugging and monitoring services
+* Integrate with external certificate management services/solutions with a pluggable interface
+* Onboard applications onto the mesh by enabling automatic sidecar injection of Envoy proxy
+
+## Install
+
+### Prerequisites
+- Kubernetes cluster running Kubernetes v1.15.0 or greater
+- kubectl current context is configured for the target cluster install
+  - ```kubectl config current-context```
+
+### Get the OSM CLI
+
+The simplest way of installing Open Service Mesh on a Kubernetes cluster is by using the `osm` CLI.
+
+Download the `osm` binary from the [Releases page](https://github.com/openservicemesh/osm/releases). Unpack the `osm` binary and add it to `$PATH` to get started.
+```shell
+sudo mv ./osm /usr/local/bin/osm
+```
+
+### Install OSM
+```shell
+$ osm install
+```
+
+![OSM Install Demo](https://github.com/openservicemesh/osm/raw/main/img/osm-install-demo-v0.2.0.gif "OSM Install Demo")

docs/content/docs/README.md

@@ -0,0 +1 @@
+place the docs in here

docs/installation_guide.md

@@ -26,13 +26,14 @@ $ make build-osm
 ## Install OSM
 Use the `osm` CLI to install the OSM control plane on to a Kubernetes cluster.
 
-**Note**: It's important to keep the version of the CLI in sync with the components it installs. Tagged releases of the CLI use the correspondingly tagged and published images by default. When using a CLI built from source, it is strongly encouraged to also build and push the OSM container images to ensure their compatibility with the CLI:
-
+Run `osm install`.
 ```console
-$ CTR_REGISTRY=myregistry CTR_TAG=mytag make docker-push-{osm-controller,init}
+# Install osm control plane components
+$ osm install
+OSM installed successfully in namespace [osm-system] with mesh name [osm]
 ```
 
-By default, the control plane components are installed into a Kubernetes Namespace called `osm-system` and the control plane is given a unique identifier attribute `mesh-name` defaulted to `osm`. Both the Namespace and mesh-name can be configured with flags to the `osm install` command.
+By default, the control plane components are installed into a Kubernetes Namespace called `osm-system` and the control plane is given a unique identifier attribute `mesh-name` defaulted to `osm`. Both the Namespace and mesh-name can be configured with flags to the `osm install` command. Running `osm install --help` provides details on the various flags that can be configured.
 
 The `mesh-name` is a unique identifier assigned to an osm-controller instance during install to identify and manage a mesh instance.
 
@@ -43,15 +44,6 @@ The `mesh-name` should follow [RFC 1123](https://tools.ietf.org/html/rfc1123) DN
 - start with an alphanumeric character
 - end with an alphanumeric character
 
- Running `osm install --help` provides details on the various flags that can be configured. For this demo, the defaults unless you need to point to custom-built images with `--container-registry` and `--osm-image-tag`.
-
-Install the control plane components with the following command, optionally with flags:
-
-```console
-$ osm install
-OSM installed successfully in namespace [osm-system] with mesh name [osm]
-```
-
 ## Inspect OSM Components
 A few components will be installed by default into the `osm-system` Namespace. Inspect them by using the following `kubectl` command:
 ```console

docs/onboard_services.md

@@ -43,7 +43,7 @@ The following guide describes how to onboard a Kubernetes microservice to an OSM
 
 1. Verify the new behavior
 
-    The OSM control plane installs Prometheus and Grafana instances by default that can be used to help make sure the application is working properly. More details can be found in the [Observability](patterns/observability/README.md) document.
+    The OSM control plane installs Prometheus and Grafana instances by default that can be used to help make sure the application is working properly. More details can be found in the [Observability](patterns/observability.md) document.
 
 
 #### Note: Removing Namespaces

docs/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@fortawesome/fontawesome-free": "^5.15.1",
+    "bootstrap": "^4.5.2"
+  }
+}