Skip to content
This repository was archived by the owner on Aug 8, 2023. It is now read-only.

Commit 6dbccc7

Browse files
jeremywiebejeremywiebe
authored
Merge pull request #130 from mobify/add-markdown-linting
Add Markdown Linting
2 parents b506c43 + 44f55d5 commit 6dbccc7

File tree

12 files changed

+290
-1
lines changed

12 files changed

+290
-1
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
*.sw[a-z]
22
.idea/
3+
node_modules

‎.remarkrc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"presets": ["lint-recommended"],
3+
"plugins": {
4+
"lint": {
5+
"code-block-style": "fenced",
6+
"fenced-code-marker": "`",
7+
"fenced-code-flag": {
8+
"allowEmpty": false
9+
},
10+
"heading-increment": true,
11+
"heading-style": "atx",
12+
"link-title-style": "\"",
13+
"list-item-bullet-indent": true,
14+
"list-item-content-indent": true,
15+
"list-item-indent": "space",
16+
"maximum-heading-length": 60,
17+
"maximum-line-length": 80,
18+
"no-consecutive-blank-lines": true,
19+
"no-duplicate-headings": true,
20+
"no-file-name-articles": true,
21+
"no-file-name-articles": true,
22+
"no-file-name-consecutive-dashes": true,
23+
"no-file-name-consecutive-dashes": true,
24+
"no-file-name-irregular-characters": true,
25+
"no-file-name-irregular-characters": true,
26+
"no-file-name-mixed-case": true,
27+
"no-file-name-mixed-case": true,
28+
"no-file-name-outer-dashes": true,
29+
"no-file-name-outer-dashes": true,
30+
"no-heading-content-indent": true,
31+
"no-heading-content-indent": true,
32+
"no-heading-indent": true,
33+
"no-heading-indent": true,
34+
"no-multiple-toplevel-headings": 0,
35+
"no-table-indentation": true,
36+
"no-tabs": true,
37+
"no-undefined-references": true,
38+
"ordered-list-marker-style": ".",
39+
"ordered-list-marker-value": "ordered",
40+
"unordered-list-marker-style": "-"
41+
}
42+
}
43+
}

‎CHANGELOG‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
Pending Release
2+
- Remove `variable-for-property` rule from sass-lint
3+
- Adds markdown linting via `lint-md` script
24
- Add ESLint and Atom Text integration how-to doc
5+
36
2.6.0
47
- Remove `variable-for-property` rule from sass-lint [#126](https://github.com/mobify/mobify-code-style/pull/126)
58
- Add the eslint jsx-a11y plugin through a new `mobify-es6-react-a11y` configuration [#129](https://github.com/mobify/mobify-code-style/pull/129)
9+
610
2.5.3
711
- Fix #123 by using react/jsx-wrap-multilines rule
812
- Migrate CSSComb documentation from Confluence to code style repo

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,3 +100,7 @@ Our Client Services team's [CSS Style Guide](/css/Readme.md). Written with a lot
100100

101101
See the `python` directory of this repo for a standardized `pylintrc` file and
102102
instructions on using `pep8`, `pylint` and `pyflakes` to check Python code.
103+
104+
## Documentation
105+
106+
See the [`docs`](docs) directory for setup and configuration of Markdown linting.

‎bin/lint-md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/bash -eu
2+
# Lints Markdown files using Mobify's `.remarkrc` configuration.
3+
NPM_BIN=$(npm bin)
4+
REMARK_RC="$NPM_BIN/../mobify-code-style/.remarkrc"
5+
REMARK_CLI="$NPM_BIN/remark"
6+
7+
$REMARK_CLI --rc-path $REMARK_RC "$@"

‎docs/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,32 @@
1+
> Write great documentation! – * [_Mobify Developer Values_](https://github.com/mobify/developer-values#️-write-great-documentation)
2+
3+
At Mobify, documentation is written in markdown.
4+
5+
Documentation should live as close as possible to the code it documents.
6+
Typically, this means including it in a `docs` folder at the root of the repo.
7+
Customer facing documentation should be published to a sub path of
8+
docs.mobify.com.
9+
10+
To make writing document easier, we provide:
11+
12+
* A linter for consistent markdown style.
13+
* A writing checklist for consistent process.
14+
15+
### Markdown Linting
16+
17+
```bash
18+
npm install --save-dev mobify-code-style
19+
20+
# 🏃 the linter markdown files in the `docs` folder:
21+
./node_modules/.bin/lint-md docs
22+
23+
# Arguments are passed to `remark-cli`: https://github.com/wooorm/remark/tree/master/packages/remark-cli
24+
./node_modules/.bin/lint-md --watch docs
25+
26+
# Try to automajically fix linting warnings:
27+
./node_modules/.bin/lint-md --output docs
28+
```
29+
130
### Writing Checklist
231

332
**Before you start writing**

‎docs/test/bad.expected.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Used to test violations of style.
2+
3+
## BAD: Starting with wrong level heading.
4+
5+
# BAD: Higher level second heading.
6+
7+
### BAD: Skipping levels between headings.
8+
9+
# BAD: Two first level headings.
10+
11+
## BAD: Repeated Headings.
12+
13+
## BAD: Repeated Headings.
14+
15+
BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
16+
17+
BAD: List immedidately following text.
18+
19+
- list
20+
21+
BAD: One space indents in lists.
22+
23+
- list
24+
25+
BAD: Two space indents in lists.
26+
27+
- list
28+
29+
BAD: Non-standard list bullet.
30+
31+
- Star
32+
33+
BAD: A non-ordered numbered list.
34+
35+
1. Number
36+
2. List
37+
38+
BAD: Fenced code-block with no language.
39+
40+
# Fenced code block
41+
42+
BAD: Indented code-block.
43+
44+
# Indented code block
45+
46+
BAD: Missing newline at end of file.
47+
docs/test/bad.md
48+
1:1 warning Missing newline character at end of file final-newline remark-lint
49+
7:1-7:43 warning Heading levels should increment by one level at a time heading-increment remark-lint
50+
9:1-9:33 warning Don’t use multiple top level headings (9:1) no-multiple-toplevel-headings remark-lint
51+
13:1-13:27 warning Do not use headings with similar content (11:1) no-duplicate-headings remark-lint
52+
15:104 warning Line must be at most 80 characters maximum-line-length remark-lint
53+
18:5 warning Incorrect list-item indent: remove 2 spaces list-item-indent remark-lint
54+
26:4 warning Incorrect list-item indent: remove 1 space list-item-indent remark-lint
55+
30:1-30:8 warning Marker style should be `-` unordered-list-marker-style remark-lint
56+
30:4 warning Incorrect list-item indent: remove 1 space list-item-indent remark-lint
57+
34:5 warning Incorrect list-item indent: remove 1 space list-item-indent remark-lint
58+
35:1-35:9 warning Marker should be `2`, was `1` ordered-list-marker-value remark-lint
59+
35:5 warning Incorrect list-item indent: remove 1 space list-item-indent remark-lint
60+
38:1 warning Remove 1 line before node no-consecutive-blank-lines remark-lint
61+
40:1-42:4 warning Missing code-language flag fenced-code-flag remark-lint
62+
46:1-46:26 warning Code blocks should be fenced code-block-style remark-lint
63+
64+
⚠ 15 warnings

‎docs/test/bad.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Used to test violations of style.
2+
3+
## BAD: Starting with wrong level heading.
4+
5+
# BAD: Higher level second heading.
6+
7+
### BAD: Skipping levels between headings.
8+
9+
# BAD: Two first level headings.
10+
11+
## BAD: Repeated Headings.
12+
13+
## BAD: Repeated Headings.
14+
15+
BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
16+
17+
BAD: List immedidately following text.
18+
- list
19+
20+
BAD: One space indents in lists.
21+
22+
- list
23+
24+
BAD: Two space indents in lists.
25+
26+
- list
27+
28+
BAD: Non-standard list bullet.
29+
30+
* Star
31+
32+
BAD: A non-ordered numbered list.
33+
34+
1. Number
35+
1. List
36+
37+
38+
BAD: Fenced code-block with no language.
39+
40+
```
41+
# Fenced code block
42+
```
43+
44+
BAD: Indented code-block.
45+
46+
# Indented code block
47+
48+
BAD: Missing newline at end of file.

‎docs/test/good.expected.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Used to test style.
2+
3+
# GOOD: Starting level one heading.
4+
5+
## GOOD: One level step down headings.
6+
7+
<!--lint disable no-duplicate-headings -->
8+
9+
### GOOD: Repeated Content when rule is disabled
10+
11+
### GOOD: Repeated Content when rule is disabled
12+
13+
<!--lint enable no-duplicate-headings -->
14+
15+
GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
16+
17+
GOOD: Bullet lists with correct bullet.
18+
19+
- A list!
20+
21+
GOOD: Ordered lists with correct numbers.
22+
23+
1. Numbered
24+
2. Listed
25+
26+
GOOD: Fenced code-blocks with langauge.
27+
28+
```python
29+
print 'Hello Mobify'
30+
```
31+
docs/test/good.md: no issues found

‎docs/test/good.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Used to test style.
2+
3+
# GOOD: Starting level one heading.
4+
5+
## GOOD: One level step down headings.
6+
7+
<!--lint disable no-duplicate-headings -->
8+
9+
### GOOD: Repeated Content when rule is disabled
10+
11+
### GOOD: Repeated Content when rule is disabled
12+
13+
<!--lint enable no-duplicate-headings -->
14+
15+
GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
16+
17+
GOOD: Bullet lists with correct bullet.
18+
19+
- A list!
20+
21+
GOOD: Ordered lists with correct numbers.
22+
23+
1. Numbered
24+
2. Listed
25+
26+
GOOD: Fenced code-blocks with langauge.
27+
28+
```python
29+
print 'Hello Mobify'
30+
```

0 commit comments

Comments
 (0)