setup markdownlint

.github/workflows/docs-parity-updates.yml

@@ -30,6 +30,11 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
       - name: Download metrics data from Moto Integration test pipeline (GitHub)
         working-directory: docs
         run: ./scripts/get_latest_github_metrics.sh ./target main
@@ -86,6 +91,13 @@ jobs:
           cp -r target/updated_coverage/md/* content/en/references/coverage && rm -R target/updated_coverage/md/
           mv -f target/updated_coverage/data/*.json data/coverage
 
+      - name: Format Parity Coverage Docs 
+        working-directory: docs
+        run: |
+          npm install
+          npm install markdownlint-cli2 --global
+          markdownlint-cli2 --config .markdownlint-cli2.yaml --fix
+
       - name: Check for changes
         id: check-for-changes
         working-directory: docs

.github/workflows/markdownlint.yml

@@ -0,0 +1,38 @@
+name: Lint Markdown Files
+on: [push, pull_request]
+
+jobs:
+  markdownlint:
+    name: 'Markdown Lint'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 2
+
+    - name: Setup Hugo
+      uses: peaceiris/actions-hugo@v3
+      with:
+        hugo-version: '0.125.6'
+        extended: true
+
+    - name: Setup Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install dependencies
+      run: |
+        npm install
+
+    - uses: tj-actions/changed-files@v24
+      id: changed-files
+      with:
+        files: 'content/**/*.md'
+        separator: "\n"
+
+    - uses: DavidAnson/markdownlint-cli2-action@v6
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        config: '.markdownlint-cli2.yaml'

.markdownlint-cli2.yaml

@@ -0,0 +1,26 @@
+globs:
+  - 'content/**/*.md'
+ignores:
+  - 'node_modules'
+  # Weird behavior with markdownlint; TODO: Fix
+  - 'content/en/tutorials/cloud-pods-collaborative-debugging/*'
+  - 'content/en/user-guide/integrations/terraform/*'
+  - 'content/en/user-guide/aws/events/*'
+customRules:
+  - markdownlint-rule-max-one-sentence-per-line
+config:
+  MD029: false # Ordered list item prefix
+  MD046: false # Code block style
+  MD025: false # Single H1
+  MD001: false # Header levels increment by one
+  MD024: false # Multiple headers with the same content
+  MD055: false # Inconsistent leading and trailing pipe characters
+  MD056: false # Inconsistent Table column count
+  MD036: false # Emphasis used instead of a header
+  MD003: false # Header style
+  MD033: false # Inline HTML
+  MD013: false # Line length
+  MD034: false # Bare URL used
+  MD032: false # Lists should be surrounded by blank lines
+  MD018: false # No space after hash on atx style header
+  MD022: false # Headers should be surrounded by blank lines

.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.13.0
+    hooks:
+      - id: markdownlint-cli2
+        args: ['--fix']

README.md

@@ -2,7 +2,6 @@
 
 Repository for [docs.localstack.cloud](https://docs.localstack.cloud).
 
-
 ## Getting Started
 
 ### Basics
@@ -12,7 +11,6 @@ LocalStack Docs is using the following technology stack:
 - [Docsy](https://docsy.dev) as a theme for Hugo.
 - [GitHub Pages](https://pages.github.com/) to automatically deploy every commit on the `main` branch of this repository on [docs.localstack.cloud](https://docs.localstack.cloud).
 
-
 ### Clone the repo
 
 Clone this repository and initialize the Git submodules recursively (`themes/docsy` is a submodule that again has submodules for vendored assets like fontawesome).
@@ -30,14 +28,13 @@ or:
     cd docs
     git submodule update --init --recursive
 
-
 ### Install Hugo
 
 LocalStack Docs is based on the [Hugo static site generator](https://gohugo.io).
 
-In order to contribute to LocalStack Docs, you need to [install Hugo](https://gohugo.io/getting-started/installing) in order to verify your changes. Make sure to install the _extended_ version of Hugo.
-You also need to make sure that `go` is installed in order to run hugo scripts. 
-
+In order to contribute to LocalStack Docs, you need to [install Hugo](https://gohugo.io/getting-started/installing) in order to verify your changes.
+Make sure to install the _extended_ version of Hugo.
+You also need to make sure that `go` is installed in order to run hugo scripts.
 
 ### Run locally
 
@@ -51,7 +48,6 @@ or run in developer mode with automatic reload:
 
 Once the server is started, the locally served Docs are available at http://localhost:1313.
 
-
 ### Writing content
 
 The whole site is generated with Hugo, a powerful static-site generator.
@@ -61,12 +57,24 @@ You can find an extensive documentation on how to use Hugo [in their docs](https
 Make sure to follow the best practices below when contributing content.
 
 #### Updating developer hub applications
+
 While contributing to the developer hub applications page i.e. editing `data/developerhub/applications.json` file, make sure to run the `create-applications.js` script in the `scripts` folder to create new application pages.
 
 Example usage in the project root:
 
     node scripts/create-applications.js
 
+### Running pre-commit checks
+
+You can run pre-commit checks to ensure that your changes are compliant with the repository's standards.
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+pre-commit will run automatically before each commit.
+If you want to run it manually, use `pre-commit run`.
 
 ## Best Practices
 
@@ -84,32 +92,35 @@ Please follow these best practices when writing documentation in this repository
   Use `bash` only for Bash scripts, and use `text` for shell outputs or command examples.
   The full list of the supported languages [here](https://gohugo.io/content-management/syntax-highlighting/).
   If needed, you can also [highlight a specific line](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences) in the snippet.
-- **Images:** If you want to use images in your post, create a new [leaf bundle directory](https://github.com/gohugoio/hugo/issues/1240) and put the image and the post (named `index.md`) in there (you can find examples in the docs already, f.e. the cognito service docs).
+- **Images:** If you want to use images in your post, create a new [leaf bundle directory](https://github.com/gohugoio/hugo/issues/1240) and put the image and the post (named `index.md`) in there (you can find examples in the docs already, f.e.
+  the cognito service docs).
   Then you can use the usual markdown syntax with a relative path (f.e.: `![Alternative_Text](file_next_to_post.png)`).
   If you want to resize the image, use the `figure` or `img` shortcode, for example: `{{< img src="cockpit-init-check.png" class="img-fluid shadow rounded" width="150px" >}}`
 - **Callouts:** Use these to make content stand out.
   The `callout` shortcode supports `note` (default), `tip` and `warning` levels.
   Use it like so:
-  ```
+
+  ```markdown
   {{< callout "warning" >}}
   This will make your computer halt and catch fire!
   {{< /callout >}}
   ```
 
-
 ## Troubleshooting
 
 This section covers common issues when working with LocalStack Docs:
 
 ### Missing shortcodes
 
 Example error:
-```
+
+```bash
 Start building sites …
 hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio
 Error: Error building site: "/home/localstack/Repos/docs-test/content/en/get-started/_index.md:57:1": failed to extract shortcode: template for shortcode "alert" not found
 Built in 45 ms
 ```
 
-1. Make sure to correctly clone and initialize the git submodules of this repo. For details see the section "[Clone the repo](#clone-the-repo)" above.
+1. Make sure to correctly clone and initialize the git submodules of this repo.
+  For details see the section "[Clone the repo](#clone-the-repo)" above.
 2. Delete the Hugo Module cache using `hugo mod clean` or `make clean`.

content/en/academy/localstack-101/lesson-2/index.md

@@ -21,7 +21,7 @@ In this lesson, we'll talk about LocalStack:
 - Tackles sophisticated and exotic APIs (QLDB, Athena, Glue) and helps enhance your skill set.
 - Contains advanced collaboration features and seamless CI integrations that foster team productivity.
 - Our mission is to empower developers with control over their environments, eliminating time-consuming cloud dev and test loops.
-- You can focus on developing exceptional products to solve real-world challenges with LocalStack as your game-changing companion. 
+- You can focus on developing exceptional products to solve real-world challenges with LocalStack as your game-changing companion.
 
 Embrace the future of cloud development and have fun exploring!
 
@@ -32,6 +32,3 @@ Further reading:
 - [LocalStack Service Coverage](https://docs.localstack.cloud/user-guide/aws/feature-coverage/)
 - [Learning Resources for Everything AWS](https://aws.amazon.com/developer/learning/)
 - [Documentation for AWS Services](https://docs.aws.amazon.com/)
-
-
-

content/en/academy/localstack-101/lesson-3/index.md

@@ -13,13 +13,14 @@ type: lessons
 url: "/academy/localstack-101/why-localstack/"
 ---
 
-Let's imagine this scenario: Alice, a software developer, takes on the task of creating a serverless 
-Web application on AWS Cloud. However, she faces slow and tedious development due to cloud dependencies (DBs, VMs, MQs, etc.).
+Let's imagine this scenario: Alice, a software developer, takes on the task of creating a serverless
+Web application on AWS Cloud.
+However, she faces slow and tedious development due to cloud dependencies (DBs, VMs, MQs, etc.).
 Every local change needs to be packaged and uploaded to the cloud for testing.
 The solution for her trouble is LocalStack — a revolutionary platform that brings cloud resources to her
 local machine, enabling efficient development and testing.
 
-LocalStack is the ultimate platform for cloud developers, offering a wide array of benefits to enhance productivity, reduce costs, and simplify maintenance. 
+LocalStack is the ultimate platform for cloud developers, offering a wide array of benefits to enhance productivity, reduce costs, and simplify maintenance.
 This comprehensive course will equip you with the knowledge and skills to harness LocalStack's power and revolutionize your cloud development workflow.
 
 Key Takeaways:
@@ -42,4 +43,3 @@ Further reading:
 - [How Understanding Billing is Complicated and Risky](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-what-is.html)
 - [LocalStack in CI](https://docs.localstack.cloud/user-guide/ci/)
 - [Third Party Integrations](https://docs.localstack.cloud/user-guide/integrations/)
-

content/en/academy/localstack-101/lesson-4/index.md

@@ -13,13 +13,14 @@ type: lessons
 url: "/academy/localstack-101/getting-started/"
 ---
 
-There are several LocalStack installation methods to kickstart your cloud development journey. 
+There are several LocalStack installation methods to kickstart your cloud development journey.
 Discover multiple pathways to initiate your LocalStack experience:
 
 You'll understand the diverse approaches to LocalStack installation:
 
 1. Quickstart with LocalStack CLI:
-- Install `awscli-local` and `localstack` via `pip install`. On macOS you can use `brew install`.
+- Install `awscli-local` and `localstack` via `pip install`.
+  On macOS you can use `brew install`.
 - Start LocalStack using `localstack start`.
 - Create a bucket and list buckets using `awslocal s3 mb s3://test` and `awslocal s3 ls`.
 2. Alternative - Docker: Dive into an alternate installation method using Docker: pull the image and run it, it's that easy.
@@ -33,6 +34,3 @@ Further reading:
 - [What is AWS CLI local](https://docs.localstack.cloud/user-guide/integrations/aws-cli/)
 - [Pip Documentation](https://pypi.org/project/pip/)
 - [Docker Compose Docs](https://docs.docker.com/get-started/08_using_compose/)
-
-
-

content/en/academy/localstack-101/lesson-5/index.md

@@ -18,9 +18,10 @@ In this informative video we guide you through the essential steps of the LocalS
 - Witness the seamless login flow and discover how to configure the web app.
 - Learn how to effortlessly connect your LocalStack Account to enable a smooth integration experience.
 - Explore the Resource Browser as we demonstrate how to list and create fundamental resources.
-- To create an account for LocalStack, visit [app.localstack.cloud/sign-up](https://app.localstack.cloud/sign-up). You can sign up with your email address or one of our supported social identity providers (such as GitHub).
+- To create an account for LocalStack, visit [app.localstack.cloud/sign-up](https://app.localstack.cloud/sign-up).
+  You can sign up with your email address or one of our supported social identity providers (such as GitHub).
 
 Further reading:
 
 - [Web App Documentation](https://docs.localstack.cloud/user-guide/web-application/)
-- [Resource Browser](https://docs.localstack.cloud/user-guide/web-application/resource-browser/)
+- [Resource Browser](https://docs.localstack.cloud/user-guide/web-application/resource-browser/)

content/en/academy/localstack-101/lesson-6/index.md

@@ -12,12 +12,13 @@ type: lessons
 url: "/academy/localstack-101/full-project-demo/"
 ---
 
-Discover the ins and outs of one of our Developer Hub's practical sample applications—a note-taking platform. 
+Discover the ins and outs of one of our Developer Hub's practical sample applications—a note-taking platform.
 This video tutorial offers a comprehensive walk-through, beginning with the checkout of the GitHub project and
-culminating in deploying the operational application on LocalStack. Covering the essentials, we'll guide you
+culminating in deploying the operational application on LocalStack.
+Covering the essentials, we'll guide you
 through dependency installation, backend and frontend build, and a detailed exploration of the application's service
 diagram to unveil the integral components at play.
 
 Further exploring:
 
-- [LocalStack Developer Hub Applications](https://docs.localstack.cloud/applications)
+- [LocalStack Developer Hub Applications](https://docs.localstack.cloud/applications)

content/en/academy/localstack-101/lesson-7/index.md

@@ -13,7 +13,7 @@ type: lessons
 url: "/academy/localstack-101/cloud-pods/"
 ---
 
-This video will cover: 
+This video will cover:
 
 What are Cloud Pods ?
 
@@ -23,7 +23,7 @@ Deviate from the default ephemeral state by leveraging Cloud Pods' capability to
 How are cloud pods useful ?
 
 - Gain insight into the advantages they offer, including the creation of shareable local cloud sandboxes.
-Learn about the collaborative potential of distributing and sharing pods among team members and discover 
+Learn about the collaborative potential of distributing and sharing pods among team members and discover
 how Cloud Pods contribute to reproducibility in applications and pre-seeding test environments.
 
 Demo

content/en/academy/localstack-development/lesson-2/index.md

@@ -11,15 +11,16 @@ type: lessons
 url: "/academy/localstack-deployment/deploy-app-ls/"
 ---
 
-In this lesson, we'll guide you through deploying a [continer-based application](https://github.com/localstack/localstack-workshop/tree/main/02-serverless-api-ecs-apigateway), which mimics the complexity of a real-world application. We are using the following AWS services and their features to build our infrastructure:
+In this lesson, we'll guide you through deploying a [continer-based application](https://github.com/localstack/localstack-workshop/tree/main/02-serverless-api-ecs-apigateway), which mimics the complexity of a real-world application.
+We are using the following AWS services and their features to build our infrastructure:
 
-  - [Elastic Container Service](https://docs.localstack.cloud/user-guide/aws/elastic-container-service/) to create and deploy our containerized application.
-  - [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) as a key-value and document database to persist our data.
-  - [API Gateway](https://docs.localstack.cloud/user-guide/aws/apigatewayv2/) to expose the containerized services to the user through HTTP APIs.
-  - [Cognito User Pools](https://docs.localstack.cloud/user-guide/aws/cognito/) for user authentication and authorizing requests to container APIs.
-  - [Amplify](https://docs.localstack.cloud/user-guide/aws/amplify/) to create the user client with ReactJS to send requests to container APIs.
-  - [S3](https://docs.localstack.cloud/user-guide/aws/s3/) to deploy the Amplify application to make the web application available to users.
-  - [IAM](https://docs.localstack.cloud/user-guide/aws/iam/) to create policies to specify roles and permissions for various AWS services.
+- [Elastic Container Service](https://docs.localstack.cloud/user-guide/aws/elastic-container-service/) to create and deploy our containerized application.
+- [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) as a key-value and document database to persist our data.
+- [API Gateway](https://docs.localstack.cloud/user-guide/aws/apigatewayv2/) to expose the containerized services to the user through HTTP APIs.
+- [Cognito User Pools](https://docs.localstack.cloud/user-guide/aws/cognito/) for user authentication and authorizing requests to container APIs.
+- [Amplify](https://docs.localstack.cloud/user-guide/aws/amplify/) to create the user client with ReactJS to send requests to container APIs.
+- [S3](https://docs.localstack.cloud/user-guide/aws/s3/) to deploy the Amplify application to make the web application available to users.
+- [IAM](https://docs.localstack.cloud/user-guide/aws/iam/) to create policies to specify roles and permissions for various AWS services.
 
 Additionally, we'll explore the **Resource Browser**, that enables you to perform basic management operations for the locally deployed AWS resources during the development and testing process, in a fashion similar to the AWS Management Console.
 
@@ -30,4 +31,3 @@ Further reading:
 - [Field Notes: Serverless Container-based APIs with Amazon ECS and Amazon API Gateway](https://aws.amazon.com/blogs/architecture/field-notes-serverless-container-based-apis-with-amazon-ecs-and-amazon-api-gateway/)
 - [What is `awslocal` CLI?](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal)
 - [LocalStack Resource Browser](https://docs.localstack.cloud/user-guide/web-application/resource-browser/)
-