Fix several typos, code snippets etc. in docs

I fixed several smaller things in the docs:

* typos
* small mistakes
  * a/an
  * duplicated/missing words/phrases
* code snippets
  * missing brackets
  * wrong indentation

Signed-off-by: Daniel Bodky <dbodky@gmail.com>

docs/docs/10-home.md

@@ -12,7 +12,7 @@ Acorn is a work in progress.  Features will evolve over time and there may be br
 
 ### What is Acorn?
 
-Acorn is an application packaging and deployment framework that simplifies running apps on Kubernetes. Acorn is able to package up all of an applications Docker images, configuration, and deployment specifications into a single Acorn image artifact. This artifact is publishable to any OCI container registry allowing it to be deployed on any dev, test, or production Kubernetes.  The portability of Acorn images enables developers to develop applications locally and move to production without having to switch tools or technology stacks.
+Acorn is an application packaging and deployment framework that simplifies running apps on Kubernetes. Acorn is able to package up all of an application's Docker images, configuration, and deployment specifications into a single Acorn image artifact. This artifact is publishable to any OCI container registry allowing it to be deployed on any dev, test, or production Kubernetes.  The portability of Acorn images enables developers to develop applications locally and move to production without having to switch tools or technology stacks.
 
 Developers create Acorn images by describing the application configuration in an [Acornfile](/authoring/overview). The Acornfile describes the whole application without all of the boilerplate of Kubernetes YAML files. The Acorn CLI is used to build, deploy, and operate Acorn images on any Kubernetes cluster.
 
@@ -33,7 +33,7 @@ Helm is a popular package manager for Kubernetes. After working with Helm charts
 specifically to offer a simplified application deployment experience for Kubernetes. Here are some of the
 differences between Acorn and Helm.
 
-1. Helm charts are templates for Kubernetes YAML files, whereas Acornfiles define application-level contructs. Acorn is
+1. Helm charts are templates for Kubernetes YAML files, whereas Acornfiles define application-level constructs. Acorn is
 a layer of abstraction on top of Kubernetes. Acorn users do not work with Kubernetes YAML files directly. By design, no Kubernetes
 knowledge is needed to use Acorn. 
 

docs/docs/30-installation/02-options.md

@@ -3,7 +3,7 @@ title: Options
 ---
 
 ## Acorn image
-When you install acorn, it will launch several workloads in your cluster, including an api-server and controller. By default, these workloads will use the `ghcr.io/acorn-io/acorn` image. You can customize this image by setting the `--image` option. This is useful if you are installing acorn in an environment where you are required to pull images from an private registry.
+When you install acorn, it will launch several workloads in your cluster, including an api-server and controller. By default, these workloads will use the `ghcr.io/acorn-io/acorn` image. You can customize this image by setting the `--image` option. This is useful if you are installing acorn in an environment where you are required to pull images from a private registry.
 
 ## TLS via Let's Encrypt
 

docs/docs/37-getting-started.md

@@ -228,7 +228,7 @@ secrets: {
     - `dirs`: Directories to mount into the container filesystem
       - `if !args.dev`: The following block applies only if the built-in development mode is **disabled** ([more on the development mode later](#step-6-development-mode))
       - `volume://pgdata?subpath=data`: references a volume defined in the top-level `volumes` section in the Acornfile and specifies the subpath `data` as the mountpoint.
-    - `files`: Similar to `dirs` but only for files. Additionally, content can be created in-line and even utilizing generating functions.
+    - `files`: Similar to `dirs` but only for files. Additionally, content can be created in-line and even utilize generating functions.
 - `localData`: Set of variables for this Acorn app
   - `food`: Custom variable, defining a list of food which is accessed in `containers.db.files` to pre-fill the database.
 - `volumes`: (persistent) data volumes to be used by any container in the Acorn app

docs/docs/38-authoring/00-overview.md

@@ -20,7 +20,7 @@ key: {
 }
 ```
 
-They start with a name `key` and are wrap a collection of fields and values in `{}`. A more Acorn specific example is:
+They start with a name `key` and wrap a collection of fields and values in `{}`. A more Acorn specific example is:
 
 ```acorn
 containers: {
@@ -30,7 +30,7 @@ containers: {
 }
 ```
 
-In the above example, there is a object called `containers`, which contains another object called `my-app`.  Keys do not need to be quoted, unless they contain a `-`.
+In the above example, there is an object called `containers`, which contains another object called `my-app`.  Keys do not need to be quoted, unless they contain a `-`.
 
 For convenience, you can collapse objects which have only one field to a single `:` line and omit the braces.  For example these:
 
@@ -113,7 +113,7 @@ localData: {
 
 Strings can be a single line or multiline.  A single line string is surrounded by `"` quotes.
 
-Multiline strings are enclosed in triple quotes `"""`. The opening `"""` must be followed by a newline. The closing `"""` must also be on it's own line. The whitespace directly preceding the closing quotles must match the preceding whitespace on all other lines and is not included not included in the value.  This allows you to indent the text to match current level without the indenting becoming part of the actual value.
+Multiline strings are enclosed in triple quotes `"""`. The opening `"""` must be followed by a newline. The closing `"""` must also be on it's own line. The whitespace directly preceding the closing quotles must match the preceding whitespace on all other lines and is not included in the value.  This allows you to indent the text to match current level without the indenting becoming part of the actual value.
 
 ```acorn
 singleLine: "Hi!"
@@ -211,7 +211,7 @@ containers: app: {
 data: port // Evaluates to 3307
 localData: {
     port: 3306
-    exposedServicePort: topLevelPort // Evaluates to 3306
+    exposedServicePort: topLevelPort // Evaluates to 3307
 }
 ```
 
@@ -333,7 +333,7 @@ Regular expression syntax is the one accepted by RE2 outlined here [https://gith
 
 ### If statements
 
-Support for standard `if` statements are available in an Acornfile. If conditions evaluate to a boolean, and apply their body if the condition is true.
+Support for standard `if` statements is available in an Acornfile. If conditions evaluate to a boolean, and apply their body if the condition is true.
 
 ```acorn
 localData: {
@@ -389,7 +389,7 @@ localData:{
     }
 }
 
-for k, v in localData.config { 
+for k, v in localData.dataVols { 
     volumes: {
        "\(k)": {}
     }

docs/docs/38-authoring/03-containers.md

@@ -19,7 +19,7 @@ containers:{
 
 ### Standard build options
 
-Acorn provides a mechanism to build your own containers for your application. If you have an existing project that already defines an Dockerfile, you can build it using Acorn.
+Acorn provides a mechanism to build your own containers for your application. If you have an existing project that already defines a Dockerfile, you can build it using Acorn.
 
 ```acorn
 containers: {
@@ -80,7 +80,7 @@ A port definition is:
 Where:
 
 * `NAME`: is an optional name for the port, like `db` or `metrics`.
-* `PORT`: is required numeric value of the port.
+* `PORT`: is the required numeric value of the port.
 * `TYPE`: is an optional value of `UDP`, `TCP`, or `HTTP`.
 
 An example of a named port:
@@ -98,7 +98,7 @@ When the user runs the built Acorn image, they can reference this port by name `
 
 ### Scopes
 
-As an author, there are three scopes used to define the ports **default** access behavior `internal`, `expose`, and `publish`. These settings can be changed at runtime by the operator.
+As an author, there are three scopes used to define the port's **default** access behavior: `internal`, `expose`, and `publish`. These settings can be changed at runtime by the operator.
 
 | Scope | Accessibility |
 | ------| --------------|
@@ -315,7 +315,7 @@ In the above example the `web` container would have 60 seconds (10 tries * 6 sec
 
 ## Defining sidecar containers
 
-Sometimes a container needs some setup before it runs, or has additional services running along side it. For these scenarios, the `sidecar` can be defined as part of the container.
+Sometimes a container needs some setup before it runs, or has additional services running alongside it. For these scenarios, the `sidecar` can be defined as part of the container.
 
 ```acorn
 containers: {

docs/docs/38-authoring/05-secrets.md

@@ -162,7 +162,7 @@ secrets: {
 }
 ```
 
-In the above example the secret renders a template secret with one key call "password.txt" the token from the secret named "token." See [advanced topics](/authoring/advanced) for other uses for the template secret type.
+In the above example the secret renders a template secret with one key called "password.txt", consuming the token from the secret named "token." See [advanced topics](/authoring/advanced) for other uses for the template secret type.
 
 ### Token secrets
 
@@ -176,9 +176,9 @@ secrets: {
             length: 32 // optional
             characters: "abcdedfhifj01234567890" // optional
         }
-    }
-    data: {
-        token: "" // optional
+        data: {
+            token: "" // optional
+        }
     }
 }
 ```

docs/docs/38-authoring/07-args-and-profiles.md

@@ -20,15 +20,15 @@ args: {
 }
 ```
 
-Arg names should be in camelCase, and when entered by the user the will be dash separated.
+Arg names should be in camelCase, and when entered by the user they will be dash separated.
 
 `thisVariableName` becomes `--this-variable-name` when the user passes it on the command line.
 
 ### Provide the user some guidance
 
 When defining arguments to the Acorn, it is helpful to the end user to also provide some context. When the user runs `acorn [IMAGE] --help` the output shows all available arguments and if defined provides a short help string.
 
-When defining args add a `// Comment` above the argument. That will be shown the user when they do a `--help`
+When defining args add a `// Comment` above the argument. That will be shown to the user when they do a `--help`
 
 ```acorn
 args: {

docs/docs/38-authoring/20-labels.md

@@ -2,7 +2,7 @@
 title: Labels and Annotations
 ---
 
-Labels and annotations are Kubernetes constructs for attaching arbitray metadata as key-value pairs to resources. Often, they are used by third-party integrations to enhance the functionality of Kubernetes. For example, if you were using [cert-manager](https://cert-manager.io/docs/) to provision SSL certificates, you could add the `cert-manager.io/cluster-issuer` annotation to your ingress resources.
+Labels and annotations are Kubernetes constructs for attaching arbitrary metadata as key-value pairs to resources. Often, they are used by third-party integrations to enhance the functionality of Kubernetes. For example, if you were using [cert-manager](https://cert-manager.io/docs/) to provision SSL certificates, you could add the `cert-manager.io/cluster-issuer` annotation to your ingress resources.
 
 To allow you to take advantage of such integrations, Acorn supports specifying labels and annotations in your Acornfile. These will be applied to the core Kubernetes resources created by Acorn.
 
@@ -44,6 +44,6 @@ containers:{
     // ...
 }
 ```
-In the above examples, the core Kubernetes resources created for the acorn container called "fronted" will get the labels and annotations. This includes the deployment, pods, ingress, and services.
+In the above examples, the core Kubernetes resources created for the acorn container called "frontend" will get the labels and annotations. This includes the deployment, pods, ingress, and services.
 
 You can also specify labels and annotations from the CLI when launching an acorn via the `run` command. See [here](running/labels) for more details.

docs/docs/38-authoring/30-advanced.md

@@ -24,7 +24,7 @@ containers: {
 
 ### Stateful applications
 
-Applications that have stateful data or where an operator would care which order the containers will be removed in a scale down event should not use the `scale` field and should instead create unique instances of the container.
+Applications that have stateful data or where an operator would care in which order the containers will be removed in a scale down event should not use the `scale` field and should instead create unique instances of the container.
 
 To accomplish this, users can leverage `for` loops in the Acornfile. Within the `for` loop all items unique to that instance should be defined. In most cases, this will be a container and data volumes. The loop can contain any of the top level objects if needed.
 
@@ -76,7 +76,10 @@ containers: {
 secrets: {
     "yaml-config": {
         type: "template"
-        data: {template: std.toYAML(localData.config)}
+        data: {
+            template: std.toYAML(localData.config)
+        }
+    }
 }
 
 localData: {
@@ -85,7 +88,7 @@ localData: {
             isGoing: {
                 to: "be a yaml file"
             }
-        }, args.userConfig)
+        }}, args.userConfig)
 }
 ```
 

docs/docs/39-publishing.md

@@ -2,7 +2,7 @@
 title: Publishing Acorn Images
 ---
 
-Once the application is in a state where it ready to move to test and production you will need to build an Acorn image and publish it to a registry. Acorn images are only accessible to the Acorn namespace they were built in. In order to use them in other namespaces or on other Kubernetes clusters, the images need to be tagged and published to a registry.
+Once the application is in a state where it is ready to move to test and production you will need to build an Acorn image and publish it to a registry. Acorn images are only accessible to the Acorn namespace they were built in. In order to use them in other namespaces or on other Kubernetes clusters, the images need to be tagged and published to a registry.
 
 ## Building and tagging an Acorn image
 
@@ -62,7 +62,7 @@ You will be prompted for your username and password to login. If your company ha
 Pushing to a registry requires 2 things:
 
 1. User is logged in and authorized.
-1. Image is tagged  the remote registry.
+1. Image is tagged for the remote registry.
 
 ```shell
 acorn push index.docker.io/myorg/image:v1.0

docs/docs/50-running/01-args-and-secrets.md

@@ -20,7 +20,7 @@ acorn run [IMAGE] --a-string "oneday" --int-arg 4 --bool-defaults-true --negate-
 
 ### Passing complex arguments
 
-To pass complex arguments is to create a file in the local directory and pass it to Acorn with the `@` syntax:
+To pass complex arguments, create a file in the local directory and pass it to Acorn with the `@` syntax:
 
 ```yaml title="config.yaml"
 my:
@@ -72,7 +72,7 @@ When this Acorn runs it will use the values in the `my-predefined-creds` secret.
 
 ### Overview
 
-Encrypted secrets provide a way to pass sensitive information to Acorn apps through public channels. To accomplish this, Acorn uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) that is encrypted with the Acorn namespaces public key. This data can only be decrypted by Acorn in the intended namespace. For convenience data can be encrypted with multiple Acorn namespace public keys and put into the same data field. At runtime Acorn will try to decrypt the data with it's own key pair. Once decrypted inside the namespace the values are stored in regular Kubernetes secrets for the app to consume. The primary use for encrypted secrets is to provide a mechanism to pass the data through untrusted systems like pipelines and command lines.
+Encrypted secrets provide a way to pass sensitive information to Acorn apps through public channels. To accomplish this, Acorn uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) that is encrypted with the Acorn namespace's public key. This data can only be decrypted by Acorn in the intended namespace. For convenience data can be encrypted with multiple Acorn namespace public keys and put into the same data field. At runtime Acorn will try to decrypt the data with its own key pair. Once decrypted inside the namespace the values are stored in regular Kubernetes secrets for the app to consume. The primary use for encrypted secrets is to provide a mechanism to pass the data through untrusted systems like pipelines and command lines.
 
 The [encryption reference section](/reference/encryption) explains how to use the Acorn public key to encrypt secrets in other languages.
 

docs/docs/50-running/04-volumes.md

@@ -34,6 +34,6 @@ You can use a precreated volumes by binding the volume at runtime.
 acorn run -v db-data:my-data [IMAGE]
 ```
 
-This Acorn app will use the volume named `db-data` as it's `my-data` volume.
+This Acorn app will use the volume named `db-data` as its `my-data` volume.
 
 The volume will match the size and class of the pre-created PV `db-data`.

docs/docs/60-architecture/02-security-considerations.md

@@ -123,7 +123,10 @@ If you need to expose your Acorn app to users and workloads outside of your clus
 
 By default, all HTTP services are automatically published via the underlying Ingress controller. To publish no ports you can use `-p none`.
 
-// Note this is going to go through a major refactor and likely to change, but the concept holds.
+:::caution
+
+Note this is going to go through a major refactor and likely to change, but the concept holds.
+:::
 
 Publishing services is a runtime level decision for the user to make. If a user wants to publish all exposed ports when launching the Acorn app the `-P` flag is used.