Update docs to fix linting issues (#904)

* add README to linter config

* fix MD004/ul-style in cli.md

* fix mkdocs import content from other files

* fix line length in migrations.doc

* add extras to linter

* fix extra README

* fix line length in dgoss README

* bump markdownlint-cli2-action@v16

---------

Co-authored-by: Ahmed Elsabbahy <[email protected]>

.github/workflows/docs.yaml

@@ -20,10 +20,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DavidAnson/markdownlint-cli2-action@v13
+      - uses: DavidAnson/markdownlint-cli2-action@v16
         with:
           globs: |
             docs/**/*.md
+            README.md
+            extras/**/README.md
+            .github/CONTRIBUTING.md
 
   build:
     runs-on: ubuntu-latest

docs/cli.md

@@ -62,12 +62,12 @@ GLOBAL OPTIONS:
 ## Commands
 
 Commands are the actions goss can run.
-- [add](#add): add a single test for a resource
-- [autoadd](#autoadd): automatically add multiple tests for a resource
-- [render](#render): renders and outputs the gossfile, importing all included gossfiles
-- [serve](#serve): serves the gossfile validation as an HTTP endpoint on a specified address and port,
+* [add](#add): add a single test for a resource
+* [autoadd](#autoadd): automatically add multiple tests for a resource
+* [render](#render): renders and outputs the gossfile, importing all included gossfiles
+* [serve](#serve): serves the gossfile validation as an HTTP endpoint on a specified address and port,
     so you can use your gossfile as a health report for the host
-- [validate](#validate): runs the goss test suite on your server
+* [validate](#validate): runs the goss test suite on your server
 
 ### `add`
 
@@ -123,22 +123,22 @@ A sub-command *resource type* has to be provided when running `add`.
 Automatically [adds](#add) all **existing** resources matching the provided argument.
 
 Will automatically add the following matching resources:
-- `file` - only if argument contains `/`
-- `group`
-- `package`
-- `port`
-- `process` - Also adding any ports it's listening to (if run as root)
-- `service`
-- `user`
+* `file` - only if argument contains `/`
+* `group`
+* `package`
+* `port`
+* `process` - Also adding any ports it's listening to (if run as root)
+* `service`
+* `user`
 
 Will **NOT** automatically add:
-- `addr`
-- `command` - for safety
-- `dns`
-- `http`
-- `interface`
-- `kernel-param`
-- `mount`
+* `addr`
+* `command` - for safety
+* `dns`
+* `http`
+* `interface`
+* `kernel-param`
+* `mount`
 
 !!! example
     ```console

docs/containers/docker-compose.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable-next-line -->
 --8<-- "extras/dcgoss/README.md"

docs/containers/docker.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable-next-line -->
 --8<-- "extras/dgoss/README.md"

docs/containers/kubernetes.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable-next-line -->
 --8<-- "extras/kgoss/README.md"

docs/contributing.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable-next-line -->
 --8<-- ".github/CONTRIBUTING.md"

docs/license.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable-next-line -->
 --8<-- "LICENSE"

docs/migrations.md

@@ -16,8 +16,8 @@ user:
       - root
 ```
 
-Goss v0.4.x, will fail with the above as group "root" is only in the slice once. However, with goss v0.4.x the array may contain
-matchers. The test below is valid for v0.4.x but not valid for v0.3.x
+Goss v0.4.x, will fail with the above as group "root" is only in the slice once. However, with goss v0.4.x the array may
+contain matchers. The test below is valid for v0.4.x but not valid for v0.3.x
 
 ```yaml
 user:

extras/dcgoss/README.md

@@ -1,14 +1,17 @@
 # dcgoss
 
-dcgoss is a convenience wrapper around goss that aims to bring the simplicity of goss to docker-compose managed containers. It is based on `dgoss`.
+dcgoss is a convenience wrapper around goss that aims to bring the simplicity of goss to docker-compose managed
+containers. It is based on `dgoss`.
 
 ## Usage
 
 `dcgoss [run|edit] <docker_run_params>`
 
 ### Run
 
-Run is used to validate a docker container defined in `docker-compose.yml`. It expects both a `docker-compose.yml` and `goss.yaml` file to exist in the directory it was invoked from. Container configuration is used from the compose file, for example:
+Run is used to validate a docker container defined in `docker-compose.yml`. It expects both a `docker-compose.yml`
+and `goss.yaml` file to exist in the directory it was invoked from. Container configuration is used from the
+compose file, for example:
 
 **run:**
 
@@ -43,7 +46,7 @@ The following environment variables can be set to change the behavior of dcgoss.
 #### DEBUG
 
 Enables debug output of `dcgoss`.
-  
+
 When running in debug mode, the tmp dir with the container output will not be cleaned up.
 
 **Default:** empty
@@ -54,7 +57,7 @@ When running in debug mode, the tmp dir with the container output will not be cl
 
 #### GOSS_PATH
 
-Location of the goss binary to use. 
+Location of the goss binary to use.
 
 **Default:** `$(which goss)`
 
@@ -104,8 +107,9 @@ If unset (or empty), the `--vars` flag is omitted, which is the normal behavior.
 
 #### GOSS_FILES_STRATEGY
 
-Strategy used for copying goss files into the docker container. 
-If set to `'mount'` a volume with goss files is mounted and log output is streamed into the container as `/goss/docker_output.log` file.
+Strategy used for copying goss files into the docker container.
+If set to `'mount'` a volume with goss files is mounted and log output is streamed into the container as
+`/goss/docker_output.log` file.
 Other strategy is `'cp'` which uses `'docker cp'` command to copy goss files into docker container.
 With the `'cp'` strategy you lose the ability to write tests or waits against the docker output.
 The `'cp'` strategy is required especially when docker daemon is not on the local machine.
@@ -114,7 +118,8 @@ The `'cp'` strategy is required especially when docker daemon is not on the loca
 
 ## Debugging test runs
 
-When debugging test execution its beneficual to set both `DEBUG=true` and `GOSS_WAIT_OPTS=-r 60s -s 5s` (without the redirect to `/dev/null`).
+When debugging test execution its beneficual to set both `DEBUG=true` and `GOSS_WAIT_OPTS=-r 60s -s 5s`
+(without the redirect to `/dev/null`).
 
 **Example:**
 

extras/dgoss/README.md

@@ -4,9 +4,11 @@ dgoss is a convenience wrapper around goss that aims to bring the simplicity of
 
 ## Examples and Tutorials
 
-* [blog tutorial](https://medium.com/@aelsabbahy/tutorial-how-to-test-your-docker-image-in-half-a-second-bbd13e06a4a9) - Introduction to dgoss tutorial
+* [blog tutorial](https://medium.com/@aelsabbahy/tutorial-how-to-test-your-docker-image-in-half-a-second-bbd13e06a4a9) -
+Introduction to dgoss tutorial
 * [video tutorial](https://youtu.be/PEHz5EnZ-FM) - Same as above, but in video format
-* [dgoss-examples](https://github.com/aelsabbahy/dgoss-examples) - Repo containing examples of using dgoss to validate docker images
+* [dgoss-examples](https://github.com/aelsabbahy/dgoss-examples) - Repo containing examples of using dgoss to validate
+docker images
 
 ## Installation
 
@@ -43,7 +45,7 @@ dgoss run ...
 
 ### Run
 
-Run is used to validate a docker container. 
+Run is used to validate a docker container.
 It expects a `./goss.yaml` file to exist in the directory it was invoked from.
 In most cases one can just substitute the docker command for the dgoss command, for example:
 
@@ -65,7 +67,9 @@ In most cases one can just substitute the docker command for the dgoss command,
 
 ### Edit
 
-Edit will launch a docker container, install goss, and drop the user into an interactive shell. Once the user quits the interactive shell, any `goss.yaml` or `goss_wait.yaml` are copied out into the current directory. This allows the user to leverage the `goss add|autoadd` commands to write tests as they would on a regular machine.
+Edit will launch a docker container, install goss, and drop the user into an interactive shell.
+Once the user quits the interactive shell, any `goss.yaml` or `goss_wait.yaml` are copied out into the current directory.
+This allows the user to leverage the `goss add|autoadd` commands to write tests as they would on a regular machine.
 
 **Example:**
 
@@ -121,17 +125,23 @@ If unset (or empty), the `--vars` flag is omitted, which is the normal behavior.
 
 #### GOSS_FILES_STRATEGY
 
-Strategy used for copying goss files into the docker container. If set to `'mount'` a volume with goss files is mounted and log output is streamed into the container as `/goss/docker_output.log` file. Other strategy is `'cp'` which uses `'docker cp'` command to copy goss files into docker container. With the `'cp'` strategy you lose the ability to write tests or waits against the docker output. The `'cp'` strategy is required especially when docker daemon is not on the local machine. 
+Strategy used for copying goss files into the docker container. If set to `'mount'` a volume with goss files is mounted
+and log output is streamed into the container as `/goss/docker_output.log` file. Other strategy is `'cp'` which uses
+`'docker cp'` command to copy goss files into docker container. With the `'cp'` strategy you lose the ability to write
+tests or waits against the docker output. The `'cp'` strategy is required especially when docker daemon is not on the
+local machine.
 (Default `'mount'`)
 
 #### CONTAINER_LOG_OUTPUT
 
-Location of the file that contains tested container logs. Logs are retained only if the variable is set to a non-empty string. (Default `''`)
+Location of the file that contains tested container logs. Logs are retained only if the variable is set to a non-empty
+string. (Default `''`)
 
 #### DGOSS_TEMP_DIR
 
 Location of the temporary directory used by dgoss. (Default `'$(mktemp -d /tmp/tmp.XXXXXXXXXX)'`)
 
 #### CONTAINER_RUNTIME
 
-Container runtime to use - `docker` or `podman`. Defaults to `docker`. Note that `podman` requires a run command to keep the container running. This defaults to `sleep infinity` in case only an image is passed to `dgoss` commands.
+Container runtime to use - `docker` or `podman`. Defaults to `docker`. Note that `podman` requires a run command to keep
+the container running. This defaults to `sleep infinity` in case only an image is passed to `dgoss` commands.

extras/kgoss/README.md

@@ -23,10 +23,10 @@ You can manually install kgoss and goss by going through the Web UI, getting
 the files and putting them in the right path. To get each of them:
 
 * **kgoss**: Run `curl -sSLO
-	https://raw.githubusercontent.com/goss-org/goss/master/extras/kgoss/kgoss`.
+  https://raw.githubusercontent.com/goss-org/goss/master/extras/kgoss/kgoss`.
 * **goss**: Download the `goss-linux-amd64` asset from
   <https://github.com/goss-org/goss/releases> and rename it `goss`. Place it
-  in your HOME directory, e.g. C:\\Users\\<username> on Windows; or set the
+  in your HOME directory, e.g. `C:\Users\<username>` on Windows; or set the
   environment variable `GOSS_PATH` to its path.
 
 ### Automatic / CLI