chore(lint): Fixed 90-95% of Markdown lint violations across the repository

.github/SECURITY.md

@@ -40,5 +40,4 @@ offer a paid security bounty program at this time.
 This project docs not provide long-term supported versions, and only the current
 release and `main` branch are actively maintained. Docker Compose v1, and the
 corresponding [v1 branch](https://github.com/docker/compose/tree/v1) reached
-EOL and are no longer supported. 
-
+EOL and are no longer supported.

.github/workflows/markdown-lint.yaml

@@ -0,0 +1,42 @@
+name: Markdown Lint Check
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md" # Run only when Markdown files change
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js & Markdownlint
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y nodejs npm
+          sudo npm install -g markdownlint-cli
+
+      - name: Run Markdownlint
+        run: |
+          markdownlint "**/*.md" --config .markdownlint.json > markdown-lint-report.txt || true
+
+      - name: Post Lint Report as PR Comment
+        if: github.event_name == 'pull_request'
+        uses: mshick/add-pr-comment@v2
+        with:
+          message: |
+            **Markdown Lint Report:**
+            ```
+            $(cat markdown-lint-report.txt)
+            ```
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          allow-repeats: false

.markdownlint.json

@@ -0,0 +1,70 @@
+{
+  "code-block-style": {
+    "style": "fenced"
+  },
+  "code-fence-style": {
+    "style": "backtick"
+  },
+  "emphasis-style": {
+    "style": "asterisk"
+  },
+  "extended-ascii": {
+    "ascii-only": false
+  },
+  "fenced-code-language": {
+    "allowed_languages": [
+      "bash",
+      "html",
+      "javascript",
+      "json",
+      "markdown",
+      "text",
+      "go"
+    ],
+    "language_only": true
+  },
+  "heading-style": {
+    "style": "atx"
+  },
+  "hr-style": {
+    "style": "---"
+  },
+  "line-length": {
+    "strict": false,
+    "code_blocks": false
+  },
+  "link-image-style": {
+    "collapsed": false,
+    "shortcut": false,
+    "url_inline": false
+  },
+  "no-duplicate-heading": {
+    "siblings_only": true
+  },
+  "ol-prefix": {
+    "style": "any"
+  },
+  "proper-names": {
+    "code_blocks": false,
+    "names": [
+      "Cake.Markdownlint",
+      "CommonMark",
+      "JavaScript",
+      "Markdown",
+      "markdown-it",
+      "markdownlint",
+      "Node.js",
+      "Docker",
+      "Go"
+    ]
+  },
+  "reference-links-images": {
+    "shortcut_syntax": true
+  },
+  "strong-style": {
+    "style": "asterisk"
+  },
+  "ul-style": {
+    "style": "dash"
+  }
+}

BUILDING.md

@@ -36,6 +36,7 @@ make test
 If you need to update a golden file simply do `go test ./... -test.update-golden`.
 
 ### End-to-end tests
+
 To run e2e tests, the Compose CLI binary needs to be built. All the commands to run e2e tests propose a version
 with the prefix `build-and-e2e` to first build the CLI before executing tests.
 
@@ -50,6 +51,7 @@ make e2e
 ```
 
 Or if you need to build the CLI, run:
+
 ```console
 make build-and-e2e
 ```
@@ -63,6 +65,7 @@ make e2e-compose
 ```
 
 Or if you need to build the CLI, run:
+
 ```console
 make build-and-e2e-compose
 ```
@@ -84,6 +87,7 @@ make build-and-e2e-compose-standalone
 ## Releases
 
 To create a new release:
+
 * Check that the CI is green on the main branch for the commit you want to release
 * Run the release GitHub Actions workflow with a tag of form vx.y.z following existing tags.
 

CONTRIBUTING.md

@@ -38,7 +38,6 @@ We also like to send gifts—if you're into Docker swag, make sure to let
 us know. We currently do not offer a paid security bounty program but are not
 ruling it out in the future.
 
-
 ## Reporting other issues
 
 A great way to contribute to the project is to send a detailed report when you
@@ -55,18 +54,18 @@ resolve the issue, please leave a comment.
 
 When reporting issues, always include:
 
-* The output of `docker version`.
-* The output of `docker context show`.
-* The output of `docker info`.
+- The output of `docker version`.
+- The output of `docker context show`.
+- The output of `docker info`.
 
 Also, include the steps required to reproduce the problem if possible and
 applicable. This information will help us review and fix your issue faster.
 When sending lengthy log files, consider posting them as a gist
-(https://gist.github.com).
+(<https://gist.github.com>).
 Don't forget to remove sensitive data from your log files before posting (you
 can replace those parts with "REDACTED").
 
-_Note:_ 
+*Note:*
 Maintainers might request additional information to diagnose an issue,
 if initial reporter doesn't answer within a reasonable delay (a few weeks),
 issue will be closed.
@@ -124,7 +123,6 @@ don't get discouraged!
   </tr>
 </table>
 
-
 ### Conventions
 
 Fork the repository and make changes on your fork in a feature branch:
@@ -267,25 +265,25 @@ We want to keep the Docker community awesome, growing and collaborative. We need
 your help to keep it that way. To help with this we've come up with some general
 guidelines for the community as a whole:
 
-* Be nice: Be courteous, respectful and polite to fellow community members:
+- Be nice: Be courteous, respectful and polite to fellow community members:
   no regional, racial, gender or other abuse will be tolerated. We like
   nice people way better than mean ones!
 
-* Encourage diversity and participation: Make everyone in our community feel
+- Encourage diversity and participation: Make everyone in our community feel
   welcome, regardless of their background and the extent of their
   contributions, and do everything possible to encourage participation in
   our community.
 
-* Keep it legal: Basically, don't get us in trouble. Share only content that
+- Keep it legal: Basically, don't get us in trouble. Share only content that
   you own, do not share private or sensitive information, and don't break
   the law.
 
-* Stay on topic: Make sure that you are posting to the correct channel and
+- Stay on topic: Make sure that you are posting to the correct channel and
   avoid off-topic discussions. Remember when you update an issue or respond
   to an email you are potentially sending it to a large number of people. Please
   consider this before you update. Also, remember that nobody likes spam.
 
-* Don't send emails to the maintainers: There's no need to send emails to the
+- Don't send emails to the maintainers: There's no need to send emails to the
   maintainers to ask them to investigate an issue or to take a look at a
   pull request. Instead of sending an email, GitHub mentions should be
   used to ping maintainers to review a pull request, a proposal or an
@@ -314,7 +312,7 @@ The rules:
    Go](https://go.dev/doc/effective_go) and [Go Code Review
    Comments](https://go.dev/wiki/CodeReviewComments).
 4. Include code comments. Tell us the why, the history and the context.
-5. Document _all_ declarations and methods, even private ones. Declare
+5. Document *all* declarations and methods, even private ones. Declare
    expectations, caveats and anything else that may be important. If a type
    gets exported, having the comments already there will ensure it's ready.
 6. Variable name length should be proportional to its context and no longer.
@@ -329,7 +327,7 @@ The rules:
    part of a util package. Just leave it unexported and well-documented.
 9. All tests should run with `go test` and outside tooling should not be
    required. No, we don't need another unit testing framework. Assertion
-   packages are acceptable if they provide _real_ incremental value.
+   packages are acceptable if they provide *real* incremental value.
 10. Even though we call these "rules" above, they are actually just
     guidelines. Since you've read all the rules, you now know that.
 

README.md

@@ -1,11 +1,13 @@
 # Table of Contents
+
 - [Docker Compose v2](#docker-compose-v2)
 - [Where to get Docker Compose](#where-to-get-docker-compose)
-    + [Windows and macOS](#windows-and-macos)
-    + [Linux](#linux)
+  - [Windows and macOS](#windows-and-macos)
+  - [Linux](#linux)
 - [Quick Start](#quick-start)
 - [Contributing](#contributing)
 - [Legacy](#legacy)
+
 # Docker Compose v2
 
 [![GitHub release](https://img.shields.io/github/v/release/docker/compose.svg?style=flat-square)](https://github.com/docker/compose/releases/latest)
@@ -40,16 +42,16 @@ Rename the relevant binary for your OS to `docker-compose` and copy it to `$HOME
 
 Or copy it into one of these folders to install it system-wide:
 
-* `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins`
-* `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins`
+- `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins`
+- `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins`
 
 (might require making the downloaded file executable with `chmod +x`)
 
-
 Quick Start
 -----------
 
 Using Docker Compose is a three-step process:
+
 1. Define your app's environment with a `Dockerfile` so it can be
    reproduced anywhere.
 2. Define the services that make up your app in `compose.yaml` so

docs/reference/compose.md

@@ -44,7 +44,6 @@ Define and run multi-container applications with Docker
 | [`wait`](compose_wait.md)       | Block until containers of all (or specified) services stop.                             |
 | [`watch`](compose_watch.md)     | Watch build context for service and rebuild/refresh containers when files are updated   |
 
-
 ### Options
 
 | Name                   | Type          | Default | Description                                                                                         |
@@ -61,23 +60,24 @@ Define and run multi-container applications with Docker
 | `--project-directory`  | `string`      |         | Specify an alternate working directory<br>(default: the path of the, first specified, Compose file) |
 | `-p`, `--project-name` | `string`      |         | Project name                                                                                        |
 
-
 <!---MARKER_GEN_END-->
 
 ## Examples
 
 ### Use `-f` to specify the name and path of one or more Compose files
+
 Use the `-f` flag to specify the location of a Compose [configuration file](/reference/compose-file/).
 
 #### Specifying multiple Compose files
+
 You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single
 configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add
 to their predecessors.
 
 For example, consider this command line:
 
 ```console
-$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db
+docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db
 ```
 
 The `docker-compose.yml` file might specify a `webapp` service.
@@ -91,6 +91,7 @@ services:
     volumes:
       - "/data"
 ```
+
 If the `docker-compose.admin.yml` also specifies this same service, any matching fields override the previous file.
 New values, add to the `webapp` service configuration.
 
@@ -112,6 +113,7 @@ The `-f` flag is optional. If you don’t provide this flag on the command line,
 and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.
 
 #### Specifying a path to a single Compose file
+
 You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either
 from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.
 
@@ -120,13 +122,14 @@ have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a
 get the postgres image for the db service from anywhere by using the `-f` flag as follows:
 
 ```console
-$ docker compose -f ~/sandbox/rails/compose.yaml pull db
+docker compose -f ~/sandbox/rails/compose.yaml pull db
 ```
 
 ### Use `-p` to specify a project name
 
 Each configuration has a project name. Compose sets the project name using
 the following mechanisms, in order of precedence:
+
 - The `-p` command line flag
 - The `COMPOSE_PROJECT_NAME` environment variable
 - The top level `name:` variable from the config file (or the last `name:`
@@ -187,6 +190,7 @@ in attached mode. Alternatively, you can also run `docker compose up --menu=fals
 
 Use `--dry-run` flag to test a command without changing your application stack state.
 Dry Run mode shows you all the steps Compose applies when executing a command, for example:
+
 ```console
 $ docker compose --dry-run up --build -d
 [+] Pulling 1/1
@@ -203,6 +207,7 @@ $ docker compose --dry-run up --build -d
  ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
  ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started
 ```
+
 From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service.  
 Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.
 

docs/reference/compose_alpha.md

@@ -10,13 +10,10 @@ Experimental commands
 | [`viz`](compose_alpha_viz.md)     | EXPERIMENTAL - Generate a graphviz graph from your compose file                                      |
 | [`watch`](compose_alpha_watch.md) | EXPERIMENTAL - Watch build context for service and rebuild/refresh containers when files are updated |
 
-
 ### Options
 
 | Name        | Type | Default | Description                     |
 |:------------|:-----|:--------|:--------------------------------|
 | `--dry-run` |      |         | Execute command in dry run mode |
 
-
 <!---MARKER_GEN_END-->
-

docs/reference/compose_alpha_dry-run.md

@@ -3,6 +3,4 @@
 <!---MARKER_GEN_START-->
 Dry run command allows you to test a command without applying changes
 
-
 <!---MARKER_GEN_END-->
-

docs/reference/compose_alpha_generate.md

@@ -12,6 +12,4 @@ EXPERIMENTAL - Generate a Compose file from existing containers
 | `--name`        | `string` |         | Project name to set in the Compose file   |
 | `--project-dir` | `string` |         | Directory to use for the project          |
 
-
 <!---MARKER_GEN_END-->
-

docs/reference/compose_alpha_publish.md

@@ -13,6 +13,4 @@ Publish compose application
 | `--with-env`              | `bool`   |         | Include environment variables in the published OCI artifact                    |
 | `-y`, `--y`               | `bool`   |         | Assume "yes" as answer to all prompts                                          |
 
-
 <!---MARKER_GEN_END-->
-