feat(docs): introduce markdownlint.json

Using markdownlint, we can codify common conventions used across the documentation to keep the styling similar. All of the defaults are used with a few exceptions: - trailing punctuation in headings are accepted (used commonly in the FAQ) - commands prefixed with terminal PS1's ($) without log output is accepted - multiple top-level headings in the same document is accepted (to workaround issues with markdownlint and hugo) - inline HTML is accepted - code blocks and table output does not need to word wrap at 80 characters for improved readability Signed-off-by: Matthew Fisher <[email protected]>
helm · Jul 6, 2020 · d688dd3 · d688dd3
1 parent c9ceaf4
commit d688dd3
Show file tree

Hide file tree

Showing 44 changed files with 1,215 additions and 795 deletions.
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -0,0 +1,11 @@
+{
+    "default": true,
+    "MD013": {
+        "code_block_line_length": 999,
+        "tables": false
+    },
+    "MD014": false,
+    "MD025": false,
+    "MD026": false,
+    "MD033": false
+}
diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
@@ -6,8 +6,9 @@ description: "Everything you need to know about how the documentation is organiz
 # Welcome
 
 Welcome to the [Helm](https://helm.sh/) documentation. Helm is the package
-manager for Kubernetes, and you can read detailed background information in
-the [CNCF Helm Project Journey report](https://www.cncf.io/cncf-helm-project-journey/).
+manager for Kubernetes, and you can read detailed background information in the
+[CNCF Helm Project Journey
+report](https://www.cncf.io/cncf-helm-project-journey/).
 
 # How the documentation is organized
 

diff --git a/content/en/docs/chart_best_practices/conventions.md b/content/en/docs/chart_best_practices/conventions.md
@@ -48,6 +48,7 @@ There are a few conventions for using the words _Helm_ and _helm_.
 - _Helm_ refers to the project as a whole
 - `helm` refers to the client-side command
 - The term `chart` does not need to be capitalized, as it is not a proper noun
-- However, `Chart.yaml` does need to be capitalized because the file name is case sensitive
+- However, `Chart.yaml` does need to be capitalized because the file name is
+  case sensitive
 
 When in doubt, use _Helm_ (with an uppercase 'H').
diff --git a/content/en/docs/chart_best_practices/custom_resource_definitions.md b/content/en/docs/chart_best_practices/custom_resource_definitions.md
@@ -39,19 +39,19 @@ installation step, you can pass the `--skip-crds` flag.
 
 #### Some caveats (and explanations)
 
-There is no support at this time for upgrading or deleting CRDs using Helm.
-This was an explicit decision after much community discussion due to the danger
-for unintentional data loss. Furthermore, there is currently no community
-consensus around how to handle CRDs and their lifecycle. As this evolves, Helm
-will add support for those use cases.
+There is no support at this time for upgrading or deleting CRDs using Helm. This
+was an explicit decision after much community discussion due to the danger for
+unintentional data loss. Furthermore, there is currently no community consensus
+around how to handle CRDs and their lifecycle. As this evolves, Helm will add
+support for those use cases.
 
 The `--dry-run` flag of `helm install` and `helm upgrade` is not currently
 supported for CRDs. The purpose of "Dry Run" is to validate that the output of
 the chart will actually work if sent to the server. But CRDs are a modification
 of the server's behavior. Helm cannot install the CRD on a dry run, so the
 discovery client will not know about that Custom Resource (CR), and validation
-will fail. You can alternatively move the CRDs to their own chart or use
-`helm template` instead.
+will fail. You can alternatively move the CRDs to their own chart or use `helm
+template` instead.
 
 Another important point to consider in the discussion around CRD support is how
 the rendering of templates is handled. One of the distinct disadvantages of the

diff --git a/content/en/docs/chart_best_practices/dependencies.md b/content/en/docs/chart_best_practices/dependencies.md
@@ -37,16 +37,17 @@ allowed in the official Helm repository.
 
 #### Experimental support for Charts hosted on OCI registries
 
-If you have [enabled experimental OCI support](/docs/registries/), you can specify
-an OCI reference (`oci://registry/group/image:tag`) for the repository URL.
+If you have [enabled experimental OCI support](/docs/registries/), you can
+specify an OCI reference (`oci://registry/group/image:tag`) for the repository
+URL.
 
 When specifying an OCI reference, you may omit the `version` argument if your
 repository URL contains an image tag (`oci://nginx:1.10`). If you do not specify
-a tag on the URL, the `version` will be used as the tag. This means that OCI URLs
-**do not support SemVer constraints**, only tagged versions are supported.
+a tag on the URL, the `version` will be used as the tag. This means that OCI
+URLs **do not support SemVer constraints**, only tagged versions are supported.
 
-If you specify both a tag and a version, the tag takes precedence and the version
-is ignored.
+If you specify both a tag and a version, the tag takes precedence and the
+version is ignored.
 
 ## Conditions and Tags
 
@@ -64,9 +65,9 @@ When multiple subcharts (dependencies) together provide an optional or swappable
 feature, those charts should share the same tags.
 
 For example, if both `nginx` and `memcached` together provide performance
-optimizations for the main app in the chart, and are required to both be
-present when that feature is enabled, then they should both have a tags section
-like this:
+optimizations for the main app in the chart, and are required to both be present
+when that feature is enabled, then they should both have a tags section like
+this:
 
 ```yaml
 tags:

diff --git a/content/en/docs/chart_best_practices/rbac.md b/content/en/docs/chart_best_practices/rbac.md
@@ -57,9 +57,9 @@ controls themselves can set this value to `false` (in which case see below).
 
 ## Using RBAC Resources
 
-`serviceAccount.name` should be set to the name of the ServiceAccount to be used by
-access-controlled resources created by the chart.  If `serviceAccount.create` is
-true, then a ServiceAccount with this name should be created.  If the name is
+`serviceAccount.name` should be set to the name of the ServiceAccount to be used
+by access-controlled resources created by the chart.  If `serviceAccount.create`
+is true, then a ServiceAccount with this name should be created.  If the name is
 not set, then a name is generated using the `fullname` template, If
 `serviceAccount.create` is false, then it should not be created, but it should
 still be associated with the same resources so that manually-created RBAC

diff --git a/content/en/docs/chart_template_guide/accessing_files.md b/content/en/docs/chart_template_guide/accessing_files.md
@@ -32,7 +32,8 @@ this works:
 - [Basic example](#basic-example)
 - [Path helpers](#path-helpers)
 - [Glob patterns](#glob-patterns)
-- [ConfigMap and Secrets utility functions](#configmap-and-secrets-utility-functions)
+- [ConfigMap and Secrets utility
+  functions](#configmap-and-secrets-utility-functions)
 - [Encoding](#encoding)
 - [Lines](#lines)
 
@@ -233,12 +234,11 @@ data:
     {{ . }}{{ end }}
 ```
 
-There is no way to pass files external to the chart during `helm
-install`. So if you are asking users to supply data, it must be loaded using
-`helm install -f` or `helm install --set`.
+There is no way to pass files external to the chart during `helm install`. So if
+you are asking users to supply data, it must be loaded using `helm install -f`
+or `helm install --set`.
 
 This discussion wraps up our dive into the tools and techniques for writing Helm
 templates. In the next section we will see how you can use one special file,
 `templates/NOTES.txt`, to send post-installation instructions to the users of
 your chart.
-
diff --git a/content/en/docs/chart_template_guide/builtin_objects.md b/content/en/docs/chart_template_guide/builtin_objects.md
@@ -26,17 +26,17 @@ access in your templates.
     upgrade or rollback.
   - `Release.IsInstall`: This is set to `true` if the current operation is an
     install.
-  - `Release.Revision`: The revision number for this release. On install, this is
-    1, and it is incremented with each upgrade and rollback.
+  - `Release.Revision`: The revision number for this release. On install, this
+    is 1, and it is incremented with each upgrade and rollback.
   - `Release.Service`: The service that is rendering the present template. On
     Helm, this is always `Helm`.
 - `Values`: Values passed into the template from the `values.yaml` file and from
   user-supplied files. By default, `Values` is empty.
 - `Chart`: The contents of the `Chart.yaml` file. Any data in `Chart.yaml` will
   be accessible here. For example `{{ .Chart.Name }}-{{ .Chart.Version }}` will
   print out the `mychart-0.1.0`.
-  - The available fields are listed in the [Charts
-    Guide]({{< ref "/docs/topics/charts.md#the-chartyaml-file" >}})
+  - The available fields are listed in the [Charts Guide]({{< ref
+    "/docs/topics/charts.md#the-chartyaml-file" >}})
 - `Files`: This provides access to all non-special files in a chart. While you
   cannot use it to access templates, you can use it to access other files in the
   chart. See the section _Accessing Files_ for more.
@@ -49,16 +49,17 @@ access in your templates.
     the given shell glob pattern.
   - `Files.Lines` is a function that reads a file line-by-line. This is useful
     for iterating over each line in a file.
-  - `Files.AsSecrets` is a function that returns the file bodies as Base 64 encoded
-    strings.
+  - `Files.AsSecrets` is a function that returns the file bodies as Base 64
+    encoded strings.
   - `Files.AsConfig` is a function that returns file bodies as a YAML map.
 - `Capabilities`: This provides information about what capabilities the
   Kubernetes cluster supports.
   - `Capabilities.APIVersions` is a set of versions.
   - `Capabilities.APIVersions.Has $version` indicates whether a version (e.g.,
     `batch/v1`) or resource (e.g., `apps/v1/Deployment`) is available on the
     cluster.
-  - `Capabilities.KubeVersion` and `Capabilities.KubeVersion.Version` is the Kubernetes version.
+  - `Capabilities.KubeVersion` and `Capabilities.KubeVersion.Version` is the
+    Kubernetes version.
   - `Capabilities.KubeVersion.Major` is the Kubernetes major version.
   - `Capabilities.KubeVersion.Minor` is the Kubernetes minor version.
 - `Template`: Contains information about the current template that is being

diff --git a/content/en/docs/chart_template_guide/control_structures.md b/content/en/docs/chart_template_guide/control_structures.md
@@ -315,9 +315,9 @@ because the scope is reset after `{{ end }}`.
   release: {{ .Release.Name }}
 ```
 
-Or, we can use `$` for accessing the object `Release.Name` from the parent scope.
-`$` is mapped to the root scope when template execution begins and it does not
-change during template execution. The following would work as well:
+Or, we can use `$` for accessing the object `Release.Name` from the parent
+scope. `$` is mapped to the root scope when template execution begins and it
+does not change during template execution. The following would work as well:
 
 ```yaml
   {{- with .Values.favorite }}

diff --git a/content/en/docs/chart_template_guide/debugging.md b/content/en/docs/chart_template_guide/debugging.md
@@ -13,8 +13,8 @@ There are a few commands that can help you debug.
 - `helm lint` is your go-to tool for verifying that your chart follows best
   practices
 - `helm install --dry-run --debug` or `helm template --debug`: We've seen this
-  trick already. It's a great way to have the server render your templates,
-  then return the resulting manifest file.
+  trick already. It's a great way to have the server render your templates, then
+  return the resulting manifest file.
 - `helm get manifest`: This is a good way to see what templates are installed on
   the server.