Skip to content

Commit 3c294d3

Browse files
dreamorosiam29d
dreamorosi
and
am29d
authored
chore(maintenance): add markdownlint (aws-powertools#2434)
* chore(maintenance): add markdownlint * chore: update lint-staged config * chore: add markdown lint step to PR CI * chore: update ignore md lint * chore: remove redundant rule config --------- Co-authored-by: Alexander Schueren <[email protected]>
1 parent 76ba994 commit 3c294d3

29 files changed

+747
-245
lines changed

‎.github/workflows/reusable-run-linting-check-and-unit-tests.yml

+16
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,19 @@ jobs:
9090
uses: ./.github/actions/cached-node-modules
9191
- name: Run linting
9292
run: npm run lint -w docs/snippets
93+
check-docs:
94+
runs-on: ubuntu-latest
95+
env:
96+
NODE_ENV: dev
97+
steps:
98+
- name: Checkout code
99+
uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
100+
- name: Setup NodeJS
101+
uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
102+
with:
103+
node-version: 20
104+
cache: "npm"
105+
- name: Setup dependencies
106+
uses: ./.github/actions/cached-node-modules
107+
- name: Run linting
108+
run: npm run lint:markdown

‎.markdownlint.yaml

+226
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Rules: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
2+
3+
# Default state for all rules
4+
default: true
5+
6+
# Path to configuration file to extend
7+
extends: null
8+
9+
# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
10+
MD001: true
11+
12+
# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
13+
# NOTE: We use h2 due to font size
14+
MD002: false
15+
16+
# MD003/heading-style/header-style - Heading style
17+
MD003:
18+
# Heading style
19+
style: "consistent"
20+
21+
# MD004/ul-style - Unordered list style
22+
MD004:
23+
# List style
24+
style: "consistent"
25+
26+
# MD005/list-indent - Inconsistent indentation for list items at the same level
27+
MD005: true
28+
29+
# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
30+
MD006: true
31+
32+
# MD007/ul-indent - Unordered list indentation
33+
MD007:
34+
# Spaces for indent
35+
indent: 4
36+
# Whether to indent the first level of the list
37+
start_indented: false
38+
# Spaces for first level indent (when start_indented is set)
39+
start_indent: 2
40+
41+
# MD009/no-trailing-spaces - Trailing spaces
42+
MD009:
43+
# Spaces for line break
44+
br_spaces: 2
45+
# Allow spaces for empty lines in list items
46+
list_item_empty_lines: false
47+
# Include unnecessary breaks
48+
strict: false
49+
50+
# MD010/no-hard-tabs - Hard tabs
51+
# NOTE: Mkdocs Material theme features like code annotations, tabbed content require it
52+
MD010: false
53+
54+
# MD011/no-reversed-links - Reversed link syntax
55+
MD011: true
56+
57+
# MD012/no-multiple-blanks - Multiple consecutive blank lines
58+
MD012:
59+
# Consecutive blank lines
60+
maximum: 1
61+
62+
# MD013/line-length - Line length
63+
MD013:
64+
# Number of characters
65+
line_length: 380
66+
# Number of characters for headings
67+
heading_line_length: 80
68+
# Number of characters for code blocks
69+
code_block_line_length: 265
70+
# Include code blocks
71+
code_blocks: true
72+
# Include tables
73+
tables: false
74+
# Include headings
75+
headings: true
76+
# Strict length checking
77+
strict: false
78+
# Stern length checking
79+
stern: false
80+
81+
# MD014/commands-show-output - Dollar signs used before commands without showing output
82+
MD014: true
83+
84+
# MD018/no-missing-space-atx - No space after hash on atx style heading
85+
MD018: true
86+
87+
# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
88+
MD019: true
89+
90+
# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
91+
MD020: true
92+
93+
# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
94+
MD021: true
95+
96+
# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
97+
MD022:
98+
# Blank lines above heading
99+
lines_above: 1
100+
# Blank lines below heading
101+
lines_below: 1
102+
103+
# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
104+
MD023: true
105+
106+
# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
107+
MD024:
108+
# Only check sibling headings
109+
siblings_only: false
110+
111+
# MD025/single-title/single-h1 - Multiple top-level headings in the same document
112+
MD025:
113+
# Heading level
114+
level: 1
115+
# RegExp for matching title in front matter
116+
front_matter_title: "^\\s*title\\s*[:=]"
117+
118+
# MD026/no-trailing-punctuation - Trailing punctuation in heading
119+
MD026:
120+
# Punctuation characters
121+
punctuation: ".,;:!。，；：！"
122+
123+
# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
124+
MD027: true
125+
126+
# MD028/no-blanks-blockquote - Blank line inside blockquote
127+
MD028: true
128+
129+
# MD029/ol-prefix - Ordered list item prefix
130+
MD029:
131+
# List style
132+
style: "one_or_ordered"
133+
134+
# MD030/list-marker-space - Spaces after list markers
135+
MD030:
136+
# Spaces for single-line unordered list items
137+
ul_single: 1
138+
# Spaces for single-line ordered list items
139+
ol_single: 1
140+
# Spaces for multi-line unordered list items
141+
ul_multi: 1
142+
# Spaces for multi-line ordered list items
143+
ol_multi: 1
144+
145+
# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
146+
MD031:
147+
# Include list items
148+
list_items: true
149+
150+
# MD032/blanks-around-lists - Lists should be surrounded by blank lines
151+
MD032: true
152+
153+
# MD033/no-inline-html - Inline HTML
154+
# NOTE: Some content like Logger '<module>' triggers false positives
155+
MD033: false
156+
157+
# MD034/no-bare-urls - Bare URL used
158+
MD034: true
159+
160+
# MD035/hr-style - Horizontal rule style
161+
MD035:
162+
# Horizontal rule style
163+
style: "consistent"
164+
165+
# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
166+
# NOTE: We use **<topic>** instead of yet another sub-heading that might not appear in the navigation.
167+
# this is a trade-off we make to not a gigantic right-navigation
168+
MD036: false
169+
170+
# MD037/no-space-in-emphasis - Spaces inside emphasis markers
171+
MD037: true
172+
173+
# MD038/no-space-in-code - Spaces inside code span elements
174+
# mkdocs-material requires these in tab content
175+
MD038: false
176+
177+
# MD039/no-space-in-links - Spaces inside link text
178+
MD039: true
179+
180+
# MD040/fenced-code-language - Fenced code blocks should have a language specified
181+
MD040: true
182+
183+
# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
184+
MD041:
185+
# Heading level
186+
level: 1
187+
# RegExp for matching title in front matter
188+
front_matter_title: "^\\s*title\\s*[:=]"
189+
190+
# MD042/no-empty-links - No empty links
191+
# NOTE: Clipboard links like Lambda Layers use empty links
192+
MD042: false
193+
194+
# MD043/required-headings/required-headers - Required heading structure
195+
MD043: false
196+
197+
# MD044/proper-names - Proper names should have the correct capitalization
198+
MD044:
199+
# List of proper names
200+
names: []
201+
# Include code blocks
202+
code_blocks: true
203+
# Include HTML elements
204+
html_elements: true
205+
206+
# MD045/no-alt-text - Images should have alternate text (alt text)
207+
MD045: true
208+
209+
# MD046/code-block-style - Code block style
210+
# Material theme tabbed content feature use indented and simple use fenced; can't support both
211+
MD046: false
212+
213+
# MD047/single-trailing-newline - Files should end with a single newline character
214+
MD047: true
215+
216+
# MD048/code-fence-style - Code fence style
217+
MD048: false
218+
219+
# MD051/link-fragments - Link fragments should be valid
220+
MD051: true
221+
222+
# MD052/reference-links-images - Reference links and images should use a label that is defined
223+
MD052: true
224+
225+
# MD053/link-image-reference-definitions - Link and image reference definitions should be needed
226+
MD053: true

‎.markdownlintignore

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# built artifacts
2+
site/**
3+
api/**
4+
# changelogs - these are not linted as they are auto-generated
5+
CHANGELOG.md
6+
packages/*/CHANGELOG.md
7+
examples/*/CHANGELOG.md
8+
layers/*/CHANGELOG.md
9+
# other files
10+
LICENSE
11+
.github/**
12+
**node_modules/** */
13+
# these will be removed from the ignore and linted in future PRs
14+
packages/batch/README.md
15+
packages/commons/README.md
16+
packages/idempotency/README.md
17+
packages/jmespath/README.md
18+
packages/logger/README.md
19+
packages/metrics/README.md
20+
packages/parameters/README.md
21+
packages/parser/README.md
22+
packages/tracer/README.md

‎CODE_OF_CONDUCT.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
## Code of Conduct
1+
# Code of Conduct
2+
23
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
34
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
4-
[email protected] with any additional questions or comments.
5+
<[email protected]> with any additional questions or comments.

‎CONTRIBUTING.md

+17-12
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,44 @@
1+
# Contributing Guidelines <!-- omit in toc -->
2+
13
## Table of contents <!-- omit in toc -->
24

35
- [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests)
46
- [Contributing via Pull Requests](#contributing-via-pull-requests)
5-
- [Dev setup](#dev-setup)
6-
- [Gitpod](#gitpod)
7-
- [GitHub Codespaces](#github-codespaces)
8-
- [Local environment](#local-environment)
9-
- [Sending a pull request](#sending-a-pull-request)
10-
- [Local documentation](#local-documentation)
7+
- [Dev setup](#dev-setup)
8+
- [Gitpod](#gitpod)
9+
- [GitHub Codespaces](#github-codespaces)
10+
- [Local environment](#local-environment)
11+
- [Sending a pull request](#sending-a-pull-request)
12+
- [Local documentation](#local-documentation)
1113
- [Conventions](#conventions)
12-
- [General terminology and practices](#general-terminology-and-practices)
13-
- [Testing definition](#testing-definition)
14+
- [General terminology and practices](#general-terminology-and-practices)
15+
- [Testing definition](#testing-definition)
1416
- [Finding contributions to work on](#finding-contributions-to-work-on)
1517
- [Code of Conduct](#code-of-conduct)
1618
- [Security issue notifications](#security-issue-notifications)
1719
- [Licensing](#licensing)
1820

19-
# Contributing Guidelines <!-- omit in toc -->
20-
21+
<!-- markdownlint-disable MD013 -->
2122
Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Fbug%2Ctriage&projects=aws-powertools%2F7&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Ffeature-request%2Ctriage&projects=aws-powertools%2F7&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=area%2Fdocumentation%2Ctriage&projects=aws-powertools%2F7&template=documentation_improvements.yml&title=Docs%3A+TITLE), we greatly value feedback and contributions from our community.
23+
<!-- markdownlint-enable MD013 -->
2224

2325
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.
2426

2527
## Reporting Bugs/Feature Requests
2628

2729
We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
2830

31+
<!-- markdownlint-disable MD013 -->
2932
[When filing an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
33+
<!-- markdownlint-enable MD013 -->
3034

3135
## Contributing via Pull Requests
3236

3337
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
3438

3539
1. You are working against the latest source on the **main** branch, unless instructed otherwise.
3640
2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
37-
3. You discuss and agree your proposed changes under [an existing issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aupdated-desc) or a [new issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
41+
3. You discuss and agree the proposed changes under [an existing issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aupdated-desc) or a new one before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.
3842

3943
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
4044

@@ -49,6 +53,7 @@ timeline
4953
: Local tests
5054
5155
Pre-commit checks <br> (git commit) : Code linting (standards)
56+
: Markdown linting
5257
5358
Pre-Pull Request <br> (git push) : Tests (unit)
5459
@@ -111,7 +116,7 @@ GitHub provides additional document on [forking a repository](https://help.githu
111116
You might find useful to run both the documentation website and the API reference locally while contributing:
112117

113118
- **Docs website**: `npm run docs-runLocalDocker`
114-
* If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage`
119+
- If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage`
115120
- **API reference**: `npm run docs-api-build-run`
116121

117122
## Conventions

‎MAINTAINERS.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1+
<!-- markdownlint-disable MD041 -->
2+
13
> [!IMPORTANT]
2-
> Maintainers' playbook moved: https://docs.powertools.aws.dev/lambda/typescript/latest/maintainers/
4+
> Maintainers' playbook moved: <https://docs.powertools.aws.dev/lambda/typescript/latest/maintainers/>

0 commit comments

Comments
 (0)