chore(cdk-lint): add linting to README.md files (#11708)

Consistent heading structure in the `README.md` files is necessary in order to ensure consistent rendering in the Python documentation, as the rendering of the TOC tree is dependent on heading levels. The best experience is achieved by having all `README.md` files start with a `H1` heading, and subsequently contain only `H2` and deeper headings. It is also important that no heading level is skipped (i.e: a `H4` "nested" in a `H2`). This adds a `cdk-lint` stage that executes `markdownlint` on the `README.md` files, with a configuration that is crafted specifically to maximize compatibility with most Markdown parsers, and to ensure correct rendering in the Python docs. Many of these offenses can be automatically fixed by running `cdk-lint --fix` or `yarn lint --fix`, however some cannot be automatically fixed by the tool and will require human intervention. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
aws · Dec 2, 2020 · 2b1160f · 2b1160f
1 parent 0b0abe4
commit 2b1160f
Show file tree

Hide file tree

Showing 206 changed files with 2,187 additions and 1,008 deletions.
diff --git a/README.md b/README.md
@@ -56,7 +56,7 @@ Modules in the AWS Construct Library are designated Experimental while we build
 them; experimental modules may have breaking API changes in any release.  After
 a module is designated Stable, it adheres to [semantic versioning](https://semver.org/),
 and only major releases can have breaking changes. Each module's stability designation
-is available on its Overview page in the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html). 
+is available on its Overview page in the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html).
 For more information, see [Versioning](https://docs.aws.amazon.com/cdk/latest/guide/reference.html#versioning)
 in the CDK Developer Guide.
 
@@ -77,15 +77,15 @@ For a detailed walkthrough, see the [tutorial](https://docs.aws.amazon.com/cdk/l
 Install or update the [AWS CDK CLI] from npm (requires [Node.js ≥ 10.13.0](https://nodejs.org/download/release/latest-v10.x/)). We recommend using a version in [Active LTS](https://nodejs.org/en/about/releases/)
 ⚠️ versions `13.0.0` to `13.6.0` are not supported due to compatibility issues with our dependencies.
 
-```bash
+```console
 $ npm i -g aws-cdk
 ```
 
 (See [Manual Installation](./MANUAL_INSTALLATION.md) for installing the CDK from a signed .zip file).
 
 Initialize a project:
 
-```bash
+```console
 $ mkdir hello-cdk
 $ cd hello-cdk
 $ cdk init sample-app --language=typescript
@@ -111,7 +111,7 @@ export class HelloCdkStack extends cdk.Stack {
 
 Deploy this to your account:
 
-```bash
+```console
 $ cdk deploy
 ```
 
@@ -148,4 +148,4 @@ environment and submit code.
 * [Examples](https://github.com/aws-samples/aws-cdk-examples)
 * [Changelog](./CHANGELOG.md)
 * [NOTICE](./NOTICE)
-* [License](./LICENSE) 
+* [License](./LICENSE)
diff --git a/packages/@aws-cdk-containers/ecs-service-extensions/README.md b/packages/@aws-cdk-containers/ecs-service-extensions/README.md
@@ -1,10 +1,12 @@
 # CDK Construct library for building ECS services
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
 
 ---
+
 <!--END STABILITY BANNER-->
 
 This library provides a high level, extensible pattern for constructing services
@@ -182,34 +184,34 @@ requiring decentralized updates to many different services.
 Every `ServiceExtension` can implement the following hooks to modify the properties
 of constructs, or make use of the resulting constructs:
 
-* `addHooks()` - This hook is called after all the extensions are added to a
+- `addHooks()` - This hook is called after all the extensions are added to a
   ServiceDescription, but before any of the other extension hooks have been run.
   It gives each extension a chance to do some inspection of the overall ServiceDescription
   and see what other extensions have been added. Some extensions may want to register
   hooks on the other extensions to modify them. For example, the Firelens extension
   wants to be able to modify the settings of the application container to route logs
   through Firelens.
-* `modifyTaskDefinitionProps()` - This is hook is passed the proposed
+- `modifyTaskDefinitionProps()` - This is hook is passed the proposed
   ecs.TaskDefinitionProps for a TaskDefinition that is about to be created.
   This allows the extension to make modifications to the task definition props
   before the TaskDefinition is created. For example, the App Mesh extension modifies
   the proxy settings for the task.
-* `useTaskDefinition()` - After the TaskDefinition is created, this hook is
+- `useTaskDefinition()` - After the TaskDefinition is created, this hook is
   passed the actual TaskDefinition construct that was created. This allows the
   extension to add containers to the task, modify the task definition's IAM role,
   etc.
-* `resolveContainerDependencies()` - Once all extensions have added their containers,
+- `resolveContainerDependencies()` - Once all extensions have added their containers,
   each extension is given a chance to modify its container's `dependsOn` settings.
   Extensions need to check and see what other extensions were enabled and decide
   whether their container needs to wait on another container to start first.
-* `modifyServiceProps()` - Before an Ec2Service or FargateService is created, this
+- `modifyServiceProps()` - Before an Ec2Service or FargateService is created, this
   hook is passed a draft version of the service props to change. Each extension adds
   its own modifications to the service properties. For example, the App Mesh extension
   needs to modify the service settings to enable CloudMap service discovery.
-* `useService()` - After the service is created, this hook is given a chance to
+- `useService()` - After the service is created, this hook is given a chance to
   utilize that service. This is used by extensions like the load balancer or App Mesh
   extension, which create and link other AWS resources to the ECS extension.
-* `connectToService()` - This hook is called when a user wants to connect one service
+- `connectToService()` - This hook is called when a user wants to connect one service
   to another service. It allows an extension to implement logic about how to allow
   connections from one service to another. For example, the App Mesh extension implements
   this method in order to easily connect one service mesh service to another, which
@@ -305,7 +307,7 @@ const environment = Environment.fromEnvironmentAttributes(stack, 'Environment',
 We encourage the development of Community Service Extensions that support
 advanced features. Here are some useful extensions that we have reviewed:
 
-* [ListenerRulesExtension](https://www.npmjs.com/package/@wheatstalk/ecs-service-extension-listener-rules) for more precise control over Application Load Balancer rules
+- [ListenerRulesExtension](https://www.npmjs.com/package/@wheatstalk/ecs-service-extension-listener-rules) for more precise control over Application Load Balancer rules
 
 > Please submit a pull request so that we can review your service extension and
 > list it here.
diff --git a/packages/@aws-cdk/alexa-ask/README.md b/packages/@aws-cdk/alexa-ask/README.md
@@ -1,18 +1,26 @@
-## Alexa Skills Kit Construct Library
+# Alexa Skills Kit Construct Library
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
 
-> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
+> All classes with the `Cfn` prefix in this module ([CFN Resources]) are always stable and safe to use.
+>
+> [CFN Resources]: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib
 
 ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
 
-> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
+> The APIs of higher level constructs in this module are experimental and under active development.
+> They are subject to non-backward compatible changes or removal in any future version. These are
+> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
+> announced in the release notes. This means that while you may use them, you may need to update
+> your source code when upgrading to a newer version of this package.
 
 ---
+
 <!--END STABILITY BANNER-->
 
 ```ts
 import * as alexaAsk from '@aws-cdk/alexa-ask';
-```
+```
diff --git a/packages/@aws-cdk/app-delivery/README.md b/packages/@aws-cdk/app-delivery/README.md
@@ -1,40 +1,46 @@
-## Continuous Integration / Continuous Delivery for CDK Applications
+# Continuous Integration / Continuous Delivery for CDK Applications
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![Deprecated](https://img.shields.io/badge/deprecated-critical.svg?style=for-the-badge)
 
 > This API may emit warnings. Backward compatibility is not guaranteed.
 
 ---
+
 <!--END STABILITY BANNER-->
 
 This library includes a *CodePipeline* composite Action for deploying AWS CDK Applications.
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
 
-### Replacement recommended
+## Replacement recommended
 
 This library has been deprecated. We recommend you use the
 [@aws-cdk/pipelines](https://docs.aws.amazon.com/cdk/api/latest/docs/pipelines-readme.html) module instead.
 
 
-### Limitations
+## Limitations
+
 The construct library in it's current form has the following limitations:
+
 1. It can only deploy stacks that are hosted in the same AWS account and region as the *CodePipeline* is.
 2. Stacks that make use of `Asset`s cannot be deployed successfully.
 
-### Getting Started
+## Getting Started
+
 In order to add the `PipelineDeployStackAction` to your *CodePipeline*, you need to have a *CodePipeline* artifact that
 contains the result of invoking `cdk synth -o <dir>` on your *CDK App*. You can for example achieve this using a
 *CodeBuild* project.
 
 The example below defines a *CDK App* that contains 3 stacks:
+
 * `CodePipelineStack` manages the *CodePipeline* resources, and self-updates before deploying any other stack
 * `ServiceStackA` and `ServiceStackB` are service infrastructure stacks, and need to be deployed in this order
 
-```
+```plaintext
   ┏━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
   ┃     Source     ┃  ┃     Build      ┃  ┃  Self-Update    ┃  ┃             Deploy              ┃
   ┃                ┃  ┃                ┃  ┃                 ┃  ┃                                 ┃
@@ -45,9 +51,9 @@ The example below defines a *CDK App* that contains 3 stacks:
   ┗━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 ```
 
-#### `index.ts`
+### `index.ts`
 
-```typescript
+```ts
 import * as codebuild from '@aws-cdk/aws-codebuild';
 import * as codepipeline from '@aws-cdk/aws-codepipeline';
 import * as codepipeline_actions from '@aws-cdk/aws-codepipeline-actions';
@@ -138,7 +144,8 @@ deployStage.addAction(new cicd.PipelineDeployStackAction({
 }));
 ```
 
-#### `buildspec.yml`
+### `buildspec.yml`
+
 The repository can contain a file at the root level named `buildspec.yml`, or
 you can in-line the buildspec. Note that `buildspec.yaml` is not compatible.
 

diff --git a/packages/@aws-cdk/assert/README.md b/packages/@aws-cdk/assert/README.md
@@ -1,17 +1,23 @@
-## Testing utilities and assertions for CDK libraries
+# Testing utilities and assertions for CDK libraries
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
 
-> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
+> The APIs of higher level constructs in this module are experimental and under active development.
+> They are subject to non-backward compatible changes or removal in any future version. These are
+> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
+> announced in the release notes. This means that while you may use them, you may need to update
+> your source code when upgrading to a newer version of this package.
 
 ---
+
 <!--END STABILITY BANNER-->
 
 This library contains helpers for writing unit tests and integration tests for CDK libraries
 
-### Unit tests
+## Unit tests
 
 Write your unit tests like this:
 
@@ -27,7 +33,7 @@ expect(stack).to(someExpectation(...));
 
 Here are the expectations you can use:
 
-### Verify (parts of) a template
+## Verify (parts of) a template
 
 Check that the synthesized stack template looks like the given template, or is a superset of it. These functions match logical IDs and all properties of a resource.
 
@@ -57,7 +63,7 @@ expect(stack).to(beASupersetOfTemplate({
 ```
 
 
-### Check existence of a resource
+## Check existence of a resource
 
 If you only care that a resource of a particular type exists (regardless of its logical identifier), and that *some* of its properties are set to specific values:
 
@@ -114,13 +120,13 @@ expect(stack).to(haveResourceLike('AWS::IAM::Policy', {
 }));
 ```
 
-### Capturing values from a match
+## Capturing values from a match
 
 Special `Capture` matchers exist to capture values encountered during a match. These can be
 used for two typical purposes:
 
-* Apply additional assertions to the values found during a matching operation.
-* Use the value found during a matching operation in a new matching operation.
+- Apply additional assertions to the values found during a matching operation.
+- Use the value found during a matching operation in a new matching operation.
 
 `Capture` matchers take an inner matcher as an argument, and will only capture the value
 if the inner matcher succeeds in matching the given value.
@@ -173,7 +179,7 @@ same value: the last value encountered by the `Capture` (as determined by the
 behavior of the matchers around it) is stored into it and will be the one
 available after the match has completed.
 
-### Check number of resources
+## Check number of resources
 
 If you want to assert that `n` number of resources of a particular type exist, with or without specific properties:
 
@@ -194,16 +200,19 @@ expect(stack).to(countResourcesLike('AWS::ApiGateway::Method', 1, {
 }));
 ```
 
-### Check existence of an output
+## Check existence of an output
+
 `haveOutput` assertion can be used to check that a stack contains specific output.
 Parameters to check against can be:
+
 - `outputName`
 - `outputValue`
 - `exportName`
 
 If `outputValue` is provided, at least one of `outputName`, `exportName` should be provided as well
 
 Example
+
 ```ts
 expect(synthStack).to(haveOutput({
   outputName: 'TestOutputName',

diff --git a/packages/@aws-cdk/assets/README.md b/packages/@aws-cdk/assets/README.md
@@ -1,12 +1,14 @@
-## AWS CDK Assets
+# AWS CDK Assets
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![Deprecated](https://img.shields.io/badge/deprecated-critical.svg?style=for-the-badge)
 
 > This API may emit warnings. Backward compatibility is not guaranteed.
 
 ---
+
 <!--END STABILITY BANNER-->
 
-All types moved to @aws-cdk/core.
+All types moved to @aws-cdk/core.
diff --git a/packages/@aws-cdk/aws-accessanalyzer/README.md b/packages/@aws-cdk/aws-accessanalyzer/README.md
@@ -1,12 +1,16 @@
-## AWS::AccessAnalyzer Construct Library
+# AWS::AccessAnalyzer Construct Library
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
 
-> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
+> All classes with the `Cfn` prefix in this module ([CFN Resources]) are always stable and safe to use.
+>
+> [CFN Resources]: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib
 
 ---
+
 <!--END STABILITY BANNER-->
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.

diff --git a/packages/@aws-cdk/aws-acmpca/README.md b/packages/@aws-cdk/aws-acmpca/README.md
@@ -1,12 +1,16 @@
-## AWS::ACMPCA Construct Library
+# AWS::ACMPCA Construct Library
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
 
-> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
+> All classes with the `Cfn` prefix in this module ([CFN Resources]) are always stable and safe to use.
+>
+> [CFN Resources]: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib
 
 ---
+
 <!--END STABILITY BANNER-->
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.

diff --git a/packages/@aws-cdk/aws-amazonmq/README.md b/packages/@aws-cdk/aws-amazonmq/README.md
@@ -1,12 +1,16 @@
-## Amazon MQ Construct Library
+# Amazon MQ Construct Library
 <!--BEGIN STABILITY BANNER-->
+
 ---
 
 ![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
 
-> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
+> All classes with the `Cfn` prefix in this module ([CFN Resources]) are always stable and safe to use.
+>
+> [CFN Resources]: https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib
 
 ---
+
 <!--END STABILITY BANNER-->
 
 ```ts