Skip to content

Commit 17937d8

Browse files
heitorlessaheitorlessa
authored
docs(lint): add markdownlint rules and automation (aws-powertools#1256)
1 parent b0527d5 commit 17937d8

21 files changed

+421
-181
lines changed

‎.github/workflows/python_docs.yml

+5-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ on:
55
branches:
66
- develop
77
paths:
8-
- 'docs/**'
9-
- 'CHANGELOG.md'
10-
- 'mkdocs.yml'
8+
- "docs/**"
9+
- "CHANGELOG.md"
10+
- "mkdocs.yml"
1111

1212
jobs:
1313
docs:
@@ -22,6 +22,8 @@ jobs:
2222
python-version: "3.8"
2323
- name: Install dependencies
2424
run: make dev
25+
- name: Lint documentation
26+
run: make lint-docs
2527
- name: Setup doc deploy
2628
run: |
2729
git config --global user.name Docs deploy

‎.markdownlint.yaml

+244
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
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+
# Include headings
77+
headers: true
78+
# Strict length checking
79+
strict: false
80+
# Stern length checking
81+
stern: false
82+
83+
# MD014/commands-show-output - Dollar signs used before commands without showing output
84+
MD014: true
85+
86+
# MD018/no-missing-space-atx - No space after hash on atx style heading
87+
MD018: true
88+
89+
# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
90+
MD019: true
91+
92+
# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
93+
MD020: true
94+
95+
# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
96+
MD021: true
97+
98+
# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
99+
MD022:
100+
# Blank lines above heading
101+
lines_above: 1
102+
# Blank lines below heading
103+
lines_below: 1
104+
105+
# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
106+
MD023: true
107+
108+
# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
109+
MD024:
110+
# Only check sibling headings
111+
allow_different_nesting: false
112+
# Only check sibling headings
113+
siblings_only: false
114+
115+
# MD025/single-title/single-h1 - Multiple top-level headings in the same document
116+
MD025:
117+
# Heading level
118+
level: 1
119+
# RegExp for matching title in front matter
120+
front_matter_title: "^\\s*title\\s*[:=]"
121+
122+
# MD026/no-trailing-punctuation - Trailing punctuation in heading
123+
MD026:
124+
# Punctuation characters
125+
punctuation: ".,;:!。，；：！"
126+
127+
# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
128+
MD027: true
129+
130+
# MD028/no-blanks-blockquote - Blank line inside blockquote
131+
MD028: true
132+
133+
# MD029/ol-prefix - Ordered list item prefix
134+
MD029:
135+
# List style
136+
style: "one_or_ordered"
137+
138+
# MD030/list-marker-space - Spaces after list markers
139+
MD030:
140+
# Spaces for single-line unordered list items
141+
ul_single: 1
142+
# Spaces for single-line ordered list items
143+
ol_single: 1
144+
# Spaces for multi-line unordered list items
145+
ul_multi: 1
146+
# Spaces for multi-line ordered list items
147+
ol_multi: 1
148+
149+
# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
150+
MD031:
151+
# Include list items
152+
list_items: true
153+
154+
# MD032/blanks-around-lists - Lists should be surrounded by blank lines
155+
MD032: true
156+
157+
# MD033/no-inline-html - Inline HTML
158+
# NOTE: Some content like Logger '<module>' triggers false positives
159+
MD033: false
160+
161+
# MD034/no-bare-urls - Bare URL used
162+
MD034: true
163+
164+
# MD035/hr-style - Horizontal rule style
165+
MD035:
166+
# Horizontal rule style
167+
style: "consistent"
168+
169+
# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
170+
# NOTE: We use **<topic>** instead of yet another sub-heading that might not appear in the navigation.
171+
# this is a trade-off we make to not a gigantic right-navigation
172+
MD036: false
173+
174+
# MD037/no-space-in-emphasis - Spaces inside emphasis markers
175+
MD037: true
176+
177+
# MD038/no-space-in-code - Spaces inside code span elements
178+
# mkdocs-material requires these in tab content
179+
MD038: false
180+
181+
# MD039/no-space-in-links - Spaces inside link text
182+
MD039: true
183+
184+
# MD040/fenced-code-language - Fenced code blocks should have a language specified
185+
MD040: true
186+
187+
# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
188+
MD041:
189+
# Heading level
190+
level: 2
191+
# RegExp for matching title in front matter
192+
front_matter_title: "^\\s*title\\s*[:=]"
193+
194+
# MD042/no-empty-links - No empty links
195+
# NOTE: Clipboard links like Lambda Layers use empty links
196+
MD042: false
197+
198+
# MD043/required-headings/required-headers - Required heading structure
199+
# NOTE: Enforce our minimum headers across the docs
200+
MD043:
201+
# List of headings
202+
headings:
203+
[
204+
"*",
205+
"## Key features",
206+
"*",
207+
"## Getting started",
208+
"*",
209+
"## Advanced",
210+
"*",
211+
"## Testing your code",
212+
"*",
213+
]
214+
215+
# MD044/proper-names - Proper names should have the correct capitalization
216+
MD044:
217+
# List of proper names
218+
names: []
219+
# Include code blocks
220+
code_blocks: true
221+
# Include HTML elements
222+
html_elements: true
223+
224+
# MD045/no-alt-text - Images should have alternate text (alt text)
225+
MD045: true
226+
227+
# MD046/code-block-style - Code block style
228+
# Material theme tabbed content feature use indented and simple use fenced; can't support both
229+
MD046: false
230+
231+
# MD047/single-trailing-newline - Files should end with a single newline character
232+
MD047: true
233+
234+
# MD048/code-fence-style - Code fence style
235+
MD048: false
236+
237+
# MD051/link-fragments - Link fragments should be valid
238+
MD051: true
239+
240+
# MD052/reference-links-images - Reference links and images should use a label that is defined
241+
MD052: true
242+
243+
# MD053/link-image-reference-definitions - Link and image reference definitions should be needed
244+
MD053: true

‎.pre-commit-config.yaml

+32-27
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,35 @@
44
# All checks can be run locally via `make pr`
55

66
repos:
7-
- repo: https://github.com/pre-commit/pre-commit-hooks
8-
rev: v2.4.0
9-
hooks:
10-
- id: check-merge-conflict
11-
- id: trailing-whitespace
12-
- id: end-of-file-fixer
13-
- id: check-toml
14-
- repo: local
15-
hooks:
16-
- id: black
17-
name: formatting::black
18-
entry: poetry run black
19-
language: system
20-
types: [python]
21-
- id: isort
22-
name: formatting::isort
23-
entry: poetry run isort
24-
language: system
25-
types: [python]
26-
- repo: local
27-
hooks:
28-
- id: flake8
29-
name: linting::flake8
30-
entry: poetry run flake8
31-
language: system
32-
types: [python]
33-
exclude: example
7+
- repo: https://github.com/pre-commit/pre-commit-hooks
8+
rev: v2.4.0
9+
hooks:
10+
- id: check-merge-conflict
11+
- id: trailing-whitespace
12+
- id: end-of-file-fixer
13+
- id: check-toml
14+
- repo: local
15+
hooks:
16+
- id: black
17+
name: formatting::black
18+
entry: poetry run black
19+
language: system
20+
types: [python]
21+
- id: isort
22+
name: formatting::isort
23+
entry: poetry run isort
24+
language: system
25+
types: [python]
26+
- repo: local
27+
hooks:
28+
- id: flake8
29+
name: linting::flake8
30+
entry: poetry run flake8
31+
language: system
32+
types: [python]
33+
exclude: example
34+
- repo: https://github.com/igorshubovych/markdownlint-cli
35+
rev: "11c08644ce6df850480d98f628596446a526cbc6" # frozen: v0.31.1
36+
hooks:
37+
- id: markdownlint
38+
args: ["--fix"]

‎Makefile

+7-1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ format:
1616
lint: format
1717
poetry run flake8 aws_lambda_powertools/* tests/*
1818

19+
lint-docs:
20+
docker run -v ${PWD}:/markdown 06kellyjac/markdownlint-cli "docs"
21+
22+
lint-docs-fix:
23+
docker run -v ${PWD}:/markdown 06kellyjac/markdownlint-cli --fix "docs"
24+
1925
test:
2026
poetry run pytest -m "not perf" --cov=aws_lambda_powertools --cov-report=xml
2127
poetry run pytest --cache-clear tests/performance
@@ -29,7 +35,7 @@ coverage-html:
2935
pre-commit:
3036
pre-commit run --show-diff-on-failure
3137

32-
pr: lint mypy pre-commit test security-baseline complexity-baseline
38+
pr: lint lint-docs mypy pre-commit test security-baseline complexity-baseline
3339

3440
build: pr
3541
poetry build

‎docs/changelog.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
[comment]: <> (Includes Changelog content entire file as a snippet)
2+
<!-- changelog is partially generated, so it doesn't follow headings and required structure, so we disable it. -->
3+
<!-- markdownlint-disable -->
24
--8<-- "CHANGELOG.md"

0 commit comments

Comments
 (0)