adding docs

.github/run-linter-locally.md

@@ -0,0 +1,85 @@
+# Run Super-Linter locally to test your branch of code
+If you want to test locally against the **Super-Linter** to test your branch of code, you will need to complete the following:
+- Clone your testing source code to your local environment
+- Install Docker to your local environment
+- Pull the container down
+- Run the container
+- Debug/Troubleshoot
+
+## Install Docker to your local machine
+You can follow the link below on how to install and configure **Docker** on your local machine
+- [Docker Install Documentation](https://docs.docker.com/install/)
+
+## Download the latest Super-Linter Docker container
+- Pull the latest **Docker** container down from **DockerHub**
+  - `docker pull admiralawkbar/super-linter:latest`
+Once the container has been downloaded to your local environment, you can then begin the process, or running the container against your codebase.
+
+## Run the container Locally
+- You can run the container locally with the following **Base** flags to run your code:
+  - `docker run -e RUN_LOCAL=true -v /path/to/local/codebase:/tmp/lint admiralawkbar/super-linter`
+  - **NOTE:** you need to pass the `RUN_LOCAL` flag to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to `/tmp/lint` so that the linter can pick up the code
+- You can add as many **Additional** flags as needed:
+  - **VALIDATE_ALL_CODEBASE**
+    - `-e VALIDATE_ALL_CODEBASE=<true|false>`
+    - Default: `true`
+    - Will parse the entire repository and find all files to validate across all types
+    - **NOTE:** When set to `false`, only **new** or **edited** files will be parsed for validation
+  - **VALIDATE_YAML**
+    - `-e VALIDATE_YAML=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_JSON**
+    - `-e VALIDATE_JSON=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_XML**
+    - `-e VALIDATE_XML=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_MD**
+    - `-e VALIDATE_MD=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_BASH**
+    - `-e VALIDATE_BASH=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_PERL**
+    - `-e VALIDATE_PERL=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_PYTHON**
+    - `-e VALIDATE_PYTHON=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_RUBY**
+    - `-e VALIDATE_RUBY=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_COFFEE**
+    - `-e VALIDATE_COFFEE=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_ANSIBLE**
+    - `-e VALIDATE_ANSIBLE=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **VALIDATE_JAVASCRIPT**
+    - `-e VALIDATE_JAVASCRIPT=<true|false>`
+    - Default: `true`
+    - Flag to enable or disable the linting process of the language
+  - **ANSIBLE_DIRECTORY**
+    - `-e ANSIBLE_DIRECTORY=</path/local/to/codebase/with/ansible>`
+    - Default: `/ansible`
+    - Flag to set the root directory for Ansible file location(s)
+
+## Troubleshooting
+
+### Run container and gain access to the command line
+If you need to run the container locally and gain access to its command line, you can run the following command:
+- `docker run -it --entrypoint /bin/bash admiralawkbar/super-linter`
+- This will drop you in the command line of the docker container for any testing or troubleshooting that may be needed.
+
+### Found issues
+If you find a *bug* or *issue*, please open a **GitHub** issue at: `https://github.com/github/super-linter/issues`

README.md

@@ -1,9 +1,7 @@
 # Super-Linter
-
 This repository is for the **GitHub** Action to run a **Super-Linter**.  
 Developers on **GitHub** can call this Action to lint their code base with the following list of linters:
 
-
 - **Ruby** (Rubocop)
 - **Shell** (Shellcheck)
 - **Ansible** (Ansible-lint)
@@ -17,7 +15,6 @@ Developers on **GitHub** can call this Action to lint their code base with the f
 - **Javascript** (eslint)(standard)
 
 ## How to use
-
 To use this **GitHub** Action you will need to complete the following:
 - Copy **any** or **all** template rules files from `TEMPLATES/` into your repository in the location: `.github/linters/`
   - If your repository does not have rules files, they will fall back to defaults in this repositories `TEMPLATE` folder
@@ -25,7 +22,6 @@ To use this **GitHub** Action you will need to complete the following:
 - Enjoy your more stable, and cleaner code base
 
 ### Example connecting GitHub Action Workflow
-
 In your repository you should have a `workflows` folder with **GitHub** Action similar to below:
 
 - `.github/workflows/linter.yml`
@@ -81,6 +77,7 @@ jobs:
           VALIDATE_ANSIBLE: false
 ...
 ```
+
 ## Env Vars
 The super-linter allows you to pass the following `ENV` variables to be able to trigger different functionality:
 - **VALIDATE_ALL_CODEBASE**
@@ -123,16 +120,17 @@ The super-linter allows you to pass the following `ENV` variables to be able to
 - **ANSIBLE_DIRECTORY**
   - Default: `/ansible`
   - Flag to set the root directory for Ansible file location(s)
-## Docker Hub
 
+## Docker Hub
 The **Docker** container that is built from this repository is located at `https://cloud.docker.com/u/admiralawkbar/repository/docker/admiralawkbar/super-linter`
 
-## How to contribute
+## Running Super-Linter locally (troubleshooting/debugging/enhancements)
+If you find that you need to run super-linter locally, you can follow the documentation at [Running super-linter locally](https://github.com/github/super-linter/blob/master/.github/run-linter-locally.md)
 
+## How to contribute
 If you would like to help contribute to this **Github** Action, please see [CONTRIBUTING](https://github.com/github/super-linter/blob/master/.github/CONTRIBUTING.md)
 
 --------------------------------------------------------------------------------
 
 ### License
-
 - [License](https://github.com/github/super-linter/blob/master/LICENSE)