Format headers

Signed-off-by: Webster Mudge <wmudge@cloudera.com>

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 Thank you for considering contributions to the `cldr-runner` project!
 
-## Submitting a pull request
+# Submitting a pull request
 
 You can start work on issues that are not yet part of a [Milestone](https://github.com/cloudera-labs/cldr-runner/milestones) -- anything in our issue tracker that isn't assigned to a Milestone is considered the [backlog](https://github.com/cloudera-labs/cldr-runner/issues?q=is%3Aopen+is%3Aissue+no%3Amilestone). 
 
@@ -21,7 +21,7 @@ As a _best practice_, you can prefix your branches with:
 > [!NOTE]
 > :fire_extinguisher: A **hotfix** should branch from `main`. It will then be committed to both the `main` and `devel` branches.
 
-## Signing your commits
+# Signing your commits
 
 Note that we require signed commits inline with [Developer Certificate of Origin](https://developercertificate.org/) best-practices for open source collaboration.
 
@@ -77,6 +77,6 @@ Signed-off-by: John Doe <jdoe@example.com>
 > [!NOTE]
 > :rocket: TIP! Add the sign-off automatically when creating the commit via the `-s` flag, e.g. `git commit -s`.
 
-## Still have questions? Opinions? Comments?
+# Have questions? Opinions? Comments?
 
 Come find us on our [Discussions](https://github.com/cloudera-labs/cldr-runner/discussions)!

FAQ.md

@@ -2,19 +2,21 @@
 
 Be sure to check out the [Discussions > Help](https://github.com/cloudera-labs/cldr-runner/discussions/categories/help) category for the latest answers. 
 
-## `ansible-navigator` FAQ
+# `ansible-navigator` FAQ
 
-### How to I add _extra variables_ and tags to `ansible-navigator`?
+## How do I add _extra variables_ and tags to `ansible-navigator`?
 
 If you want to run a playbook with a given tag, e.g. `-t infra`, then simply add it as a parameter to the `ansible-navigator` commandline. For example, `ansible-navigator run playbook.yml -t infra`. 
 
 Like tags, so you can pass _extra variables_ to `ansible-navigator` and the underlying Ansible command. For example, `ansible-navigator run playbook.yml -e @some_config.yml -e some_var=yes`.
 
-### How do I tell `ansible-navigator` where to find collections and roles?
+## How do I tell `ansible-navigator` where to find collections and roles?
 
-By default, `cloudera-deploy` expects to use the collections, roles, and libraries within the _execution environment_ container, that is, the `cldr-runner` image. Make sure you do _not_ have `ANSIBLE_COLLECTIONS_PATH` or `ANSIBLE_ROLES_PATH` set or `ansible-navigator` will pick up these environment variables and pass them to the running container. The underlying `ansible` application, like `ansible-playbook` will then pick up these environment variables and attempt to use them if set! This behavior is great if you want to use host-based collections, e.g. local development, but you need to ensure that you update the `ansible-navigator.yml` configuration file to mount the host collection and/or role directories into the execution environment container. See [Advanced Usage: Execution Modes](NAVIGATOR.md#advanced-usage-execution-modes) to learn more about these execution modes.
+By default, `cloudera-deploy` expects to use the collections, roles, and libraries within the _execution environment_ container, that is, the `cldr-runner` image. Make sure you do _not_ have `ANSIBLE_COLLECTIONS_PATH` or `ANSIBLE_ROLES_PATH` set or `ansible-navigator` will pick up these environment variables and pass them to the running container. The underlying `ansible` application, like `ansible-playbook` will then pick up these environment variables and attempt to use them if set! 
 
-### `ansible-navigator` hangs when I run my playbook. What is going on?
+This behavior is great if you want to use host-based collections, e.g. local development, but you need to ensure that you update the `ansible-navigator.yml` configuration file to mount the host collection and/or role directories into the execution environment container. See [Advanced Usage: Execution Modes](NAVIGATOR.md#advanced-usage-execution-modes) to learn more about these execution modes.
+
+## `ansible-navigator` hangs when I run my playbook. What is going on?
 
 `ansible-navigator` does not handle user prompts when running in the `curses`, text-based UI , so actions in your playbook like:
 
@@ -32,7 +34,7 @@ ansible-navigator run --enable-prompts ...
 
 to your execution to allow `ansible-navigator` to receive your prompt input.
 
-### How can I view a previous `ansible-navigator` run to debug an issue?
+## How can I view a previous `ansible-navigator` run to debug an issue?
 
 `ansible-navigator` can be configured to save execution runs to a directory. You can reload a run by using the `replay` command:
 
@@ -44,15 +46,15 @@ Then you can use the TUI to review the plays, tasks, and inventory for the previ
 
 You can learn more about [replays](https://ansible.readthedocs.io/projects/navigator/subcommands/#ansible-navigator-subcommands) and their [configuration](https://ansible.readthedocs.io/projects/navigator/settings/#subcommand-replay) in the `ansible-navigator` documentation.
 
-### How can I enable the playbook debugger?
+## How can I enable the playbook debugger?
 
 The [playbook debugger](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_debugger.html) is enabled in `ansible-navigator` by setting the debugger and then enabling prompts. For example,
 
 ```bash
 ANSIBLE_ENABLE_TASK_DEBUGGER=True ansible-navigator run --enable-prompts main.yml
 ```
 
-### How to I configure SSH to avoid a "Failed to connect to new control master" error?
+## How to I configure SSH to avoid a "Failed to connect to new control master" error?
 
 When running connecting to a host via SSH while running `ansible-navigator`, in particular when you are working with Terraform inventory managed by the `cloud.terraform` inventory plugin, you might encounter the following error:
 

NAVIGATOR.md

@@ -2,7 +2,7 @@
 
 > `ansible-navigator` is a command-line tool and a text-based user interface (TUI) for creating, reviewing, running and troubleshooting Ansible content, including inventories, playbooks, collections, documentation and container images (execution environments).
 
-## Installation
+# Installation
 
 Setting up `ansible-navigator` is easy; you can spin up a new setup in **TWO** steps (plus your OS requirements, see note below for important details)!
 
@@ -25,11 +25,11 @@ Setting up `ansible-navigator` is easy; you can spin up a new setup in **TWO** s
 > [!IMPORTANT]
 > Please note each OS has slightly different requirements for installing `ansible-navigator`. :woozy_face: Read more about [installing `ansible-navigator`](https://ansible.readthedocs.io/projects/navigator/installation/#install-ansible-navigator).
 
-## Usage
+# Usage
 
 `ansible-navigator` can be viewed as a wrapper around the core Ansible application, like `ansible-playbook`, `ansible-galaxy`, `ansible-doc`, etc. Read more about how to [configure](https://ansible.readthedocs.io/projects/navigator/settings/) your setup and your project execution as well as the [mapping](https://ansible.readthedocs.io/projects/navigator/subcommands/#mapping-ansible-navigator-commands-to-ansible-commands) of and [running](https://ansible.readthedocs.io/projects/navigator/subcommands/) of these subcommands.
 
-### Common commands
+## Common commands
 
 | Command | Description |
 |---------|-------------|
@@ -38,21 +38,21 @@ Setting up `ansible-navigator` is easy; you can spin up a new setup in **TWO** s
 | `ansible-navigator doc cloudera.cloud.datahub_service -t lookup` | View the `ansible-docs` of the [`cloudera.cloud.datahub_service` lookup](https://wmudge.github.io/cloudera.cloud/datahub_service_lookup.html) plugin. |
 | `ansible-navigator exec -- ansible localhost -m cloudera.cloud.env_info -a 'name=my_env'` | Query the Cloudera Data Platform (CDP) Public Cloud for details on the `my_env` Environment. |
 
-## Advanced Usage: Execution Modes
+# Advanced Usage: Execution Modes
 
 `ansible-navigator` typically executes Ansible using the Ansible runtime, collections, and roles built into the _execution environment_, but this is not the only way you can use the tool. In fact, there are **four** modes of execution with `ansible-navigator`, each providing a growing degree of control and customization as well as complexity. Yet, `ansible-navigator` provides a common interface to all modes, allowing you to switch seamlessly from one mode to another.
 
 Each mode is enabled by the presence of certain paths (e.g. `ANSIBLE_COLLECTIONS_PATHS`, `./collections`) and configuration parameters (e.g. `--execution-environment`).
 
-### User Mode
+## User Mode
 
 | Collections path | Ansible runtime |
 |------------------|-----------------|
 | container | container |
 
 This is the default mode for using _execution environments_ like `cldr-runner`. All executable assets and dependencies are bundled into the image. All that is needed to run is `ansible-navigator` itself; the tool will collect and inject everything into the running container.
 
-### Power User Mode
+## Power User Mode
 
 | Collections path | Ansible runtime |
 |------------------|-----------------|
@@ -62,7 +62,7 @@ If `ansible-navigator` discovers a `./collections` directory in the project, it
 
 See the [Placement of Ansible collections](https://ansible.readthedocs.io/projects/navigator/faq/#placement-of-ansible-collections) section for further details.
 
-### Developer Mode
+## Developer Mode
 
 | Collections path | Ansible runtime |
 |------------------|-----------------|
@@ -85,7 +85,7 @@ See the [Placement of Ansible collections](https://ansible.readthedocs.io/projec
 
 The [local development](README.md#local-development) instructions are designed to support this mode. 
 
-### Platform Mode
+## Platform Mode
 
 | Collections path | Ansible runtime |
 |------------------|-----------------|
@@ -108,6 +108,6 @@ See the [Execution Environment configuration](https://ansible.readthedocs.io/pro
 
 This is a fairly common task then [running CI jobs](https://github.com/cloudera-labs/cloudera.cluster/blob/main/.github/workflows/validate_pr.yml) for individual collections. The [local development](README.md#local-development) instructions are designed to support this mode.
 
-## Troubleshooting
+# Troubleshooting
 
 The [Frequently Asked Questions](FAQ.md) guide has a collection of relevant troubleshooting topics. You can also stop by the [Discussion > Help](https://github.com/cloudera-labs/cldr-runner/discussions/categories/help) category for the latest answers.

README.md

@@ -16,7 +16,7 @@ Specifically, the project consists of `execution-environment.yml` configuration
 | [gcp](gcp/execution-environment.yml) | `base` plus GCP-specific collections and dependencies, including the `gcloud` CLI |
 | [full](full/execution-environment.yml) | All of the above, plus additional CLI tools for in-container usage, e.g. `git`, `vim`, `nano`, `tree`, `kubectl` |
 
-## Quickstart
+# Quickstart
 
 `cldr-runner` is designed to run with `ansible-navigator` and other _Execution Environment_-based tools. You might want to [install `ansible-navigator`](NAVIGATOR.md) before delving deeper.
 
@@ -25,7 +25,7 @@ Specifically, the project consists of `execution-environment.yml` configuration
 3. [Customizing or extending images](#customizing)
 4. [Making a local development environment](#local-development)
 
-## Roadmap
+# Roadmap
 
 If you want to see what we are working on or have pending, check out:
 
@@ -35,15 +35,15 @@ If you want to see what we are working on or have pending, check out:
 
 Are we missing something? Let us know by [creating a new issue](https://github.com/cloudera-labs/cldr-runner/issues/new) or [posting a new idea](https://github.com/cloudera-labs/cldr-runner/discussions/new?category=ideas)!
 
-## Contributing
+# Contributing
 
 For more information on how to get involved with the `cldr-runner` project, head over to [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Installing and Using
+# Installing and Using
 
 You can run Ansible within `cldr-runner` Execution Environments a couple of different ways. Here are the most common:
 
-### `ansible-navigator` 
+## `ansible-navigator` 
 
 Using a `cldr-runner` image in the [`ansible-navigator` application](https://ansible.readthedocs.io/projects/navigator/) as the designated [Execution Environment](https://docs.ansible.com/ansible/devel/getting_started_ee/index.html) is straightforward. Update your `ansible-navigator.yml` configuration file to enable the image:
 
@@ -62,15 +62,15 @@ Once defined, you can run your Ansible activities within the resulting `cldr-run
 > [!NOTE]
 > If you want to "drop into" the container directly, i.e. run a shell within the container, run `ansible-navigator exec -- /bin/bash` and all the mounts, environment variables, etc. are handled for you!! Now from the shell, you can still run `ansible-playbook` and all other Ansible applications. 
 
-### AWX/AAP
+## AWX/AAP
 
 You can specify a `cldr-runner` image as an [Execution Environment](https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html).
 
 ![AWX Execution Environment setup](img/awx-ee.png)
 
 Once defined, the EE can be used by Job Templates, Container Groups, etc.
 
-### `docker run`
+## `docker run`
 
 > [!WARNING]
 > This mode of operation is not suggested. If you need direct container access, use `ansible-navigator exec -- /bin/bash` as suggested in the [section above](#ansible-navigator).
@@ -83,7 +83,7 @@ docker run -it ghcr.io/cloudera-labs/cldr-runner:aws-latest /bin/bash
 
 Take care to assemble and mount the needed directories other supporting assets; the image is based on [`ansible-runner`](https://ansible.readthedocs.io/projects/runner/en/stable/) (as are all Execution Environments) and runs as such.
 
-## Building
+# Building
 
 If you need to construct a local image, first set up a Python virtual environment with the latest `ansible-core` and `ansible-builder`:
 
@@ -110,7 +110,7 @@ images:
 
 The resulting image will now be loaded into your local image cache.
 
-## Customizing
+# Customizing
 
 A common approach to using `cldr-runner` is to use it as a base and add additional resources -- like other Ansible collections -- for use with your playbooks, and [`ansible-builder`]() handles for this activity.
 
@@ -158,7 +158,7 @@ ansible-navigator:
       policy: missing
 ```
 
-## Local Development
+# Local Development
 
 The `cldr-runner` project can also be used to bootstrap a local development environment on the native host environment (as opposed to an Execution Environment image).  This option is more involved, but can avoid issues with Docker, such as mount latencies and SSH agent forwarding, and improve overall Ansible collection development. 
 
@@ -205,7 +205,7 @@ Follow these steps to set up a local environment:
     source <your development directory>/setup-ansible-env.sh
     ```
 
-## License and Copyright
+# License and Copyright
 
 Copyright 2023, Cloudera, Inc.