mdl 0.7.0 → 0.8.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (148) hide show
  1. checksums.yaml +4 -4
  2. data/lib/mdl/doc.rb +1 -1
  3. data/lib/mdl/version.rb +1 -1
  4. data/mdl.gemspec +3 -3
  5. metadata +4 -266
  6. data/.github/ISSUE_TEMPLATE/BUG_TEMPLATE.md +0 -22
  7. data/.github/ISSUE_TEMPLATE/DESIGN_PROPOSAL.md +0 -40
  8. data/.github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md +0 -20
  9. data/.github/ISSUE_TEMPLATE/RULE_REQUEST.md +0 -20
  10. data/.github/PULL_REQUEST_TEMPLATE.md +0 -23
  11. data/.gitignore +0 -13
  12. data/.pre-commit-hooks.yaml +0 -6
  13. data/.travis.yml +0 -12
  14. data/CHANGELOG.md +0 -218
  15. data/CONTRIBUTING.md +0 -76
  16. data/MAINTAINERS.md +0 -21
  17. data/README.md +0 -87
  18. data/Rakefile +0 -8
  19. data/docs/RULES.md +0 -1089
  20. data/docs/configuration.md +0 -99
  21. data/docs/creating_rules.md +0 -90
  22. data/docs/creating_styles.md +0 -47
  23. data/docs/rolling_a_release.md +0 -51
  24. data/example/markdown_spec.md +0 -897
  25. data/test/fixtures/default_mdlrc +0 -1
  26. data/test/fixtures/dir_with_md_and_markdown/bar.markdown +0 -1
  27. data/test/fixtures/dir_with_md_and_markdown/foo.md +0 -1
  28. data/test/fixtures/front_matter/jekyll_post.md +0 -16
  29. data/test/fixtures/front_matter/jekyll_post_2.md +0 -17
  30. data/test/fixtures/mdlrc_disable_rules +0 -1
  31. data/test/fixtures/mdlrc_disable_tags +0 -1
  32. data/test/fixtures/mdlrc_enable_rules +0 -1
  33. data/test/fixtures/mdlrc_enable_tags +0 -1
  34. data/test/fixtures/my_ruleset.rb +0 -6
  35. data/test/rule_tests/alternate_top_level_header.md +0 -3
  36. data/test/rule_tests/alternate_top_level_header_style.rb +0 -4
  37. data/test/rule_tests/atx_closed_header_spacing.md +0 -17
  38. data/test/rule_tests/atx_header_spacing.md +0 -5
  39. data/test/rule_tests/blockquote_blank_lines.md +0 -31
  40. data/test/rule_tests/blockquote_spaces.md +0 -23
  41. data/test/rule_tests/bulleted_list_2_space_indent.md +0 -6
  42. data/test/rule_tests/bulleted_list_2_space_indent_style.rb +0 -3
  43. data/test/rule_tests/bulleted_list_4_space_indent.md +0 -3
  44. data/test/rule_tests/bulleted_list_not_at_beginning_of_line.md +0 -14
  45. data/test/rule_tests/code_block_consistency.md +0 -11
  46. data/test/rule_tests/code_block_consistency_style.rb +0 -1
  47. data/test/rule_tests/code_block_dollar.md +0 -33
  48. data/test/rule_tests/code_block_dollar_fence.md +0 -29
  49. data/test/rule_tests/code_block_fenced.md +0 -17
  50. data/test/rule_tests/code_block_fenced_style.rb +0 -1
  51. data/test/rule_tests/code_block_indented.md +0 -17
  52. data/test/rule_tests/code_block_indented_style.rb +0 -1
  53. data/test/rule_tests/consecutive_blank_lines.md +0 -11
  54. data/test/rule_tests/consistent_bullet_styles_asterisk.md +0 -3
  55. data/test/rule_tests/consistent_bullet_styles_dash.md +0 -3
  56. data/test/rule_tests/consistent_bullet_styles_plus.md +0 -3
  57. data/test/rule_tests/default_test_style.rb +0 -5
  58. data/test/rule_tests/emphasis_instead_of_headers.md +0 -42
  59. data/test/rule_tests/empty_doc.md +0 -0
  60. data/test/rule_tests/fenced_code_blocks.md +0 -27
  61. data/test/rule_tests/fenced_code_with_nesting.md +0 -73
  62. data/test/rule_tests/fenced_code_without_blank_lines.md +0 -42
  63. data/test/rule_tests/fenced_code_without_blank_lines_style.rb +0 -3
  64. data/test/rule_tests/first_header_bad_atx.md +0 -1
  65. data/test/rule_tests/first_header_bad_setext.md +0 -2
  66. data/test/rule_tests/first_header_good_atx.md +0 -1
  67. data/test/rule_tests/first_header_good_setext.md +0 -2
  68. data/test/rule_tests/first_line_top_level_header_atx.md +0 -3
  69. data/test/rule_tests/first_line_top_level_header_atx_style.rb +0 -2
  70. data/test/rule_tests/first_line_top_level_header_setext.md +0 -4
  71. data/test/rule_tests/first_line_top_level_header_setext_style.rb +0 -2
  72. data/test/rule_tests/fix_102_extra_nodes_in_link_text.md +0 -8
  73. data/test/rule_tests/header_duplicate_content.md +0 -11
  74. data/test/rule_tests/header_duplicate_content_different_nesting.md +0 -11
  75. data/test/rule_tests/header_duplicate_content_different_nesting_style.rb +0 -1
  76. data/test/rule_tests/header_duplicate_content_no_different_nesting.md +0 -13
  77. data/test/rule_tests/header_multiple_toplevel.md +0 -3
  78. data/test/rule_tests/header_mutliple_h1_no_toplevel.md +0 -5
  79. data/test/rule_tests/header_trailing_punctuation.md +0 -11
  80. data/test/rule_tests/header_trailing_punctuation_customized.md +0 -14
  81. data/test/rule_tests/header_trailing_punctuation_customized_style.rb +0 -2
  82. data/test/rule_tests/headers_bad.md +0 -7
  83. data/test/rule_tests/headers_good.md +0 -5
  84. data/test/rule_tests/headers_good_setext_with_atx.md +0 -7
  85. data/test/rule_tests/headers_good_setext_with_atx_style.rb +0 -2
  86. data/test/rule_tests/headers_good_with_issue_numbers.md +0 -12
  87. data/test/rule_tests/headers_surrounding_space_atx.md +0 -12
  88. data/test/rule_tests/headers_surrounding_space_setext.md +0 -15
  89. data/test/rule_tests/headers_with_spaces_at_the_beginning.md +0 -20
  90. data/test/rule_tests/hr_style_dashes.md +0 -22
  91. data/test/rule_tests/hr_style_dashes_style.rb +0 -3
  92. data/test/rule_tests/hr_style_inconsistent.md +0 -22
  93. data/test/rule_tests/hr_style_long.md +0 -22
  94. data/test/rule_tests/hr_style_long_style.rb +0 -3
  95. data/test/rule_tests/hr_style_stars.md +0 -22
  96. data/test/rule_tests/hr_style_stars_style.rb +0 -3
  97. data/test/rule_tests/inconsistent_bullet_indent_same_level.md +0 -4
  98. data/test/rule_tests/inconsistent_bullet_styles_asterisk.md +0 -3
  99. data/test/rule_tests/inconsistent_bullet_styles_dash.md +0 -3
  100. data/test/rule_tests/inconsistent_bullet_styles_plus.md +0 -3
  101. data/test/rule_tests/incorrect_bullet_style_asterisk.md +0 -3
  102. data/test/rule_tests/incorrect_bullet_style_asterisk_style.rb +0 -3
  103. data/test/rule_tests/incorrect_bullet_style_dash.md +0 -3
  104. data/test/rule_tests/incorrect_bullet_style_dash_style.rb +0 -3
  105. data/test/rule_tests/incorrect_bullet_style_plus.md +0 -3
  106. data/test/rule_tests/incorrect_bullet_style_plus_style.rb +0 -3
  107. data/test/rule_tests/incorrect_header_atx.md +0 -6
  108. data/test/rule_tests/incorrect_header_atx_closed.md +0 -6
  109. data/test/rule_tests/incorrect_header_atx_closed_style.rb +0 -2
  110. data/test/rule_tests/incorrect_header_atx_style.rb +0 -2
  111. data/test/rule_tests/incorrect_header_setext.md +0 -6
  112. data/test/rule_tests/incorrect_header_setext_style.rb +0 -2
  113. data/test/rule_tests/inline_html.md +0 -13
  114. data/test/rule_tests/links.md +0 -9
  115. data/test/rule_tests/lists_without_blank_lines.md +0 -75
  116. data/test/rule_tests/long_lines.md +0 -3
  117. data/test/rule_tests/long_lines_100.md +0 -7
  118. data/test/rule_tests/long_lines_100_style.rb +0 -3
  119. data/test/rule_tests/long_lines_code.md +0 -45
  120. data/test/rule_tests/long_lines_code_style.rb +0 -3
  121. data/test/rule_tests/mixed_header_types_atx.md +0 -6
  122. data/test/rule_tests/mixed_header_types_atx_closed.md +0 -6
  123. data/test/rule_tests/mixed_header_types_setext.md +0 -6
  124. data/test/rule_tests/no_first_line_header.md +0 -1
  125. data/test/rule_tests/no_first_line_header_style.rb +0 -1
  126. data/test/rule_tests/no_first_line_top_level_header.md +0 -1
  127. data/test/rule_tests/no_first_line_top_level_header_style.rb +0 -1
  128. data/test/rule_tests/ordered_list_item_prefix.md +0 -13
  129. data/test/rule_tests/ordered_list_item_prefix_ordered.md +0 -13
  130. data/test/rule_tests/ordered_list_item_prefix_ordered_style.rb +0 -3
  131. data/test/rule_tests/reversed_link.md +0 -7
  132. data/test/rule_tests/spaces_after_list_marker.md +0 -74
  133. data/test/rule_tests/spaces_after_list_marker_style.rb +0 -5
  134. data/test/rule_tests/spaces_inside_codespan_elements.md +0 -7
  135. data/test/rule_tests/spaces_inside_emphasis_markers.md +0 -35
  136. data/test/rule_tests/spaces_inside_link_text.md +0 -28
  137. data/test/rule_tests/trailing_spaces_br.md +0 -4
  138. data/test/rule_tests/trailing_spaces_br_style.rb +0 -3
  139. data/test/rule_tests/whitespace_issues.md +0 -3
  140. data/test/setup_tests.rb +0 -5
  141. data/test/test_cli.rb +0 -301
  142. data/test/test_ruledocs.rb +0 -52
  143. data/test/test_rules.rb +0 -58
  144. data/tools/README.md +0 -3
  145. data/tools/docker/Dockerfile +0 -13
  146. data/tools/docker/README.md +0 -19
  147. data/tools/test_location.rb +0 -20
  148. data/tools/view_markdown.rb +0 -11
data/Rakefile DELETED
@@ -1,8 +0,0 @@
1
- require 'bundler/gem_tasks'
2
- require 'rake/testtask'
3
-
4
- task :default => :test
5
-
6
- Rake::TestTask.new do |t|
7
- t.pattern = "test/test_*.rb"
8
- end
@@ -1,1089 +0,0 @@
1
-
2
- * [Rules](#rules)
3
- * [MD001 - Header levels should only increment by one level at a time](#md001---header-levels-should-only-increment-by-one-level-at-a-time)
4
- * [MD002 - First header should be a top level header](#md002---first-header-should-be-a-top-level-header)
5
- * [MD003 - Header style](#md003---header-style)
6
- * [MD004 - Unordered list style](#md004---unordered-list-style)
7
- * [MD005 - Inconsistent indentation for list items at the same level](#md005---inconsistent-indentation-for-list-items-at-the-same-level)
8
- * [MD006 - Consider starting bulleted lists at the beginning of the line](#md006---consider-starting-bulleted-lists-at-the-beginning-of-the-line)
9
- * [MD007 - Unordered list indentation](#md007---unordered-list-indentation)
10
- * [MD009 - Trailing spaces](#md009---trailing-spaces)
11
- * [MD010 - Hard tabs](#md010---hard-tabs)
12
- * [MD011 - Reversed link syntax](#md011---reversed-link-syntax)
13
- * [MD012 - Multiple consecutive blank lines](#md012---multiple-consecutive-blank-lines)
14
- * [MD013 - Line length](#md013---line-length)
15
- * [MD014 - Dollar signs used before commands without showing output](#md014---dollar-signs-used-before-commands-without-showing-output)
16
- * [MD018 - No space after hash on atx style header](#md018---no-space-after-hash-on-atx-style-header)
17
- * [MD019 - Multiple spaces after hash on atx style header](#md019---multiple-spaces-after-hash-on-atx-style-header)
18
- * [MD020 - No space inside hashes on closed atx style header](#md020---no-space-inside-hashes-on-closed-atx-style-header)
19
- * [MD021 - Multiple spaces inside hashes on closed atx style header](#md021---multiple-spaces-inside-hashes-on-closed-atx-style-header)
20
- * [MD022 - Headers should be surrounded by blank lines](#md022---headers-should-be-surrounded-by-blank-lines)
21
- * [MD023 - Headers must start at the beginning of the line](#md023---headers-must-start-at-the-beginning-of-the-line)
22
- * [MD024 - Multiple headers with the same content](#md024---multiple-headers-with-the-same-content)
23
- * [MD025 - Multiple top level headers in the same document](#md025---multiple-top-level-headers-in-the-same-document)
24
- * [MD026 - Trailing punctuation in header](#md026---trailing-punctuation-in-header)
25
- * [MD027 - Multiple spaces after blockquote symbol](#md027---multiple-spaces-after-blockquote-symbol)
26
- * [MD028 - Blank line inside blockquote](#md028---blank-line-inside-blockquote)
27
- * [MD029 - Ordered list item prefix](#md029---ordered-list-item-prefix)
28
- * [MD030 - Spaces after list markers](#md030---spaces-after-list-markers)
29
- * [MD031 - Fenced code blocks should be surrounded by blank lines](#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines)
30
- * [MD032 - Lists should be surrounded by blank lines](#md032---lists-should-be-surrounded-by-blank-lines)
31
- * [MD033 - Inline HTML](#md033---inline-html)
32
- * [MD034 - Bare URL used](#md034---bare-url-used)
33
- * [MD035 - Horizontal rule style](#md035---horizontal-rule-style)
34
- * [MD036 - Emphasis used instead of a header](#md036---emphasis-used-instead-of-a-header)
35
- * [MD037 - Spaces inside emphasis markers](#md037---spaces-inside-emphasis-markers)
36
- * [MD038 - Spaces inside code span elements](#md038---spaces-inside-code-span-elements)
37
- * [MD039 - Spaces inside link text](#md039---spaces-inside-link-text)
38
- * [MD040 - Fenced code blocks should have a language specified](#md040---fenced-code-blocks-should-have-a-language-specified)
39
- * [MD041 - First line in file should be a top level header](#md041---first-line-in-file-should-be-a-top-level-header)
40
- * [MD046 - Code block style](#md046---code-block-style)
41
-
42
- # Rules
43
-
44
- This document contains a description of all rules, what they are checking for,
45
- as well as an examples of documents that break the rule and corrected
46
- versions of the examples.
47
-
48
- ## MD001 - Header levels should only increment by one level at a time
49
-
50
- Tags: headers
51
-
52
- Aliases: header-increment
53
-
54
- This rule is triggered when you skip header levels in a markdown document, for
55
- example:
56
-
57
- # Header 1
58
-
59
- ### Header 3
60
-
61
- We skipped out a 2nd level header in this document
62
-
63
- When using multiple header levels, nested headers should increase by only one
64
- level at a time:
65
-
66
- # Header 1
67
-
68
- ## Header 2
69
-
70
- ### Header 3
71
-
72
- #### Header 4
73
-
74
- ## Another Header 2
75
-
76
- ### Another Header 3
77
-
78
-
79
- ## MD002 - First header should be a top level header
80
-
81
- Tags: headers
82
-
83
- Aliases: first-header-h1
84
-
85
- Parameters: level (number; default 1)
86
-
87
- This rule is triggered when the first header in the document isn't a h1 header:
88
-
89
- ## This isn't a H1 header
90
-
91
- ### Another header
92
-
93
- The first header in the document should be a h1 header:
94
-
95
- # Start with a H1 header
96
-
97
- ## Then use a H2 for subsections
98
-
99
- ## MD003 - Header style
100
-
101
- Tags: headers
102
-
103
- Aliases: header-style
104
-
105
- Parameters: style ("consistent", "atx", "atx_closed", "setext", "setext_with_atx"; default "consistent")
106
-
107
- This rule is triggered when different header styles (atx, setext, and 'closed'
108
- atx) are used in the same document:
109
-
110
- # ATX style H1
111
-
112
- ## Closed ATX style H2 ##
113
-
114
- Setext style H1
115
- ===============
116
-
117
- Be consistent with the style of header used in a document:
118
-
119
- # ATX style H1
120
-
121
- ## ATX style H2
122
-
123
- The setext_with_atx doc style allows atx-style headers of level 3 or more in
124
- documents with setext style headers:
125
-
126
- Setext style H1
127
- ===============
128
-
129
- Setext style H2
130
- ---------------
131
-
132
- ### ATX style H3
133
-
134
- Note: the configured header style can be a specific style to use (atx,
135
- atx_closed, setext, setext_with_atx), or simply require that the usage be
136
- consistent within the document.
137
-
138
- ## MD004 - Unordered list style
139
-
140
- Tags: bullet, ul
141
-
142
- Aliases: ul-style
143
-
144
- Parameters: style ("consistent", "asterisk", "plus", "dash"; default "consistent")
145
-
146
- This rule is triggered when the symbols used in the document for unordered
147
- list items do not match the configured unordered list style:
148
-
149
- * Item 1
150
- + Item 2
151
- - Item 3
152
-
153
- To fix this issue, use the configured style for list items throughout the
154
- document:
155
-
156
- * Item 1
157
- * Item 2
158
- * Item 3
159
-
160
- Note: the configured list style can be a specific symbol to use (asterisk,
161
- plus, dash), or simply require that the usage be consistent within the
162
- document.
163
-
164
- ## MD005 - Inconsistent indentation for list items at the same level
165
-
166
- Tags: bullet, ul, indentation
167
-
168
- Aliases: list-indent
169
-
170
- This rule is triggered when list items are parsed as being at the same level,
171
- but don't have the same indentation:
172
-
173
- * Item 1
174
- * Nested Item 1
175
- * Nested Item 2
176
- * A misaligned item
177
-
178
- Usually this rule will be triggered because of a typo. Correct the indentation
179
- for the list to fix it:
180
-
181
- * Item 1
182
- * Nested Item 1
183
- * Nested Item 2
184
- * Nested Item 3
185
-
186
- ## MD006 - Consider starting bulleted lists at the beginning of the line
187
-
188
- Tags: bullet, ul, indentation
189
-
190
- Aliases: ul-start-left
191
-
192
- This rule is triggered when top level lists don't start at the beginning of a
193
- line:
194
-
195
- Some text
196
-
197
- * List item
198
- * List item
199
-
200
- To fix, ensure that top level list items are not indented:
201
-
202
-
203
- Some test
204
-
205
- * List item
206
- * List item
207
-
208
- Rationale: Starting lists at the beginning of the line means that nested list
209
- items can all be indented by the same amount when an editor's indent function
210
- or the tab key is used to indent. Starting a list 1 space in means that the
211
- indent of the first nested list is less than the indent of the second level (3
212
- characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
213
-
214
- ## MD007 - Unordered list indentation
215
-
216
- Tags: bullet, ul, indentation
217
-
218
- Aliases: ul-indent
219
-
220
- Parameters: indent (number; default 2)
221
-
222
- This rule is triggered when list items are not indented by the configured
223
- number of spaces (default: 2).
224
-
225
- Example:
226
-
227
- * List item
228
- * Nested list item indented by 3 spaces
229
-
230
- Corrected Example:
231
-
232
- * List item
233
- * Nested list item indented by 2 spaces
234
-
235
- Rationale (2 space indent): indenting by 2 spaces allows the content of a
236
- nested list to be in line with the start of the content of the parent list
237
- when a single space is used after the list marker.
238
-
239
- Rationale (4 space indent): Same indent as code blocks, simpler for editors to
240
- implement. See
241
- <http://www.cirosantilli.com/markdown-styleguide/#indented-lists> for more
242
- information.
243
-
244
- In addition, this is a compatibility issue with multi-markdown parsers, which
245
- require a 4 space indents. See
246
- <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>
247
- for a description of the problem.
248
-
249
- ## MD009 - Trailing spaces
250
-
251
- Tags: whitespace
252
-
253
- Aliases: no-trailing-spaces
254
-
255
- Parameters: br_spaces (number; default: 0)
256
-
257
- This rule is triggered on any lines that end with whitespace. To fix this,
258
- find the line that is triggered and remove any trailing spaces from the end.
259
-
260
- The br_spaces parameter allows an exception to this rule for a specific amount
261
- of trailing spaces used to insert an explicit line break/br element. For
262
- example, set br_spaces to 2 to allow exactly 2 spaces at the end of a line.
263
-
264
- Note: you have to set br_spaces to 2 or higher for this exception to take
265
- effect - you can't insert a br element with just a single trailing space, so
266
- if you set br_spaces to 1, the exception will be disabled, just as if it was
267
- set to the default of 0.
268
-
269
- ## MD010 - Hard tabs
270
-
271
- Tags: whitespace, hard_tab
272
-
273
- Aliases: no-hard-tabs
274
-
275
- This rule is triggered by any lines that contain hard tab characters instead
276
- of using spaces for indentation. To fix this, replace any hard tab characters
277
- with spaces instead.
278
-
279
- Example:
280
-
281
- Some text
282
-
283
- * hard tab character used to indent the list item
284
-
285
- Corrected example:
286
-
287
- Some text
288
-
289
- * Spaces used to indent the list item instead
290
-
291
- ## MD011 - Reversed link syntax
292
-
293
- Tags: links
294
-
295
- Aliases: no-reversed-links
296
-
297
- This rule is triggered when text that appears to be a link is encountered, but
298
- where the syntax appears to have been reversed (the `[]` and `()` are
299
- reversed):
300
-
301
- (Incorrect link syntax)[http://www.example.com/]
302
-
303
- To fix this, swap the `[]` and `()` around:
304
-
305
- [Correct link syntax](http://www.example.com/)
306
-
307
- ## MD012 - Multiple consecutive blank lines
308
-
309
- Tags: whitespace, blank_lines
310
-
311
- Aliases: no-multiple-blanks
312
-
313
- This rule is triggered when there are multiple consecutive blank lines in the
314
- document:
315
-
316
- Some text here
317
-
318
-
319
- Some more text here
320
-
321
- To fix this, delete the offending lines:
322
-
323
- Some text here
324
-
325
- Some more text here
326
-
327
- Note: this rule will not be triggered if there are multiple consecutive blank
328
- lines inside code blocks.
329
-
330
- ## MD013 - Line length
331
-
332
- Tags: line_length
333
-
334
- Aliases: line-length
335
- Parameters: line_length, code_blocks, tables (number; default 80, boolean; default true)
336
-
337
- This rule is triggered when there are lines that are longer than the
338
- configured line length (default: 80 characters). To fix this, split the line
339
- up into multiple lines.
340
-
341
- This rule has an exception where there is no whitespace beyond the configured
342
- line length. This allows you to still include items such as long URLs without
343
- being forced to break them in the middle.
344
-
345
- You also have the option to exclude this rule for code blocks and tables. To
346
- do this, set the `code_blocks` and/or `tables` parameters to false.
347
-
348
- Code blocks are included in this rule by default since it is often a
349
- requirement for document readability, and tentatively compatible with code
350
- rules. Still, some languages do not lend themselves to short lines.
351
-
352
- ## MD014 - Dollar signs used before commands without showing output
353
-
354
- Tags: code
355
-
356
- Aliases: commands-show-output
357
-
358
- This rule is triggered when there are code blocks showing shell commands to be
359
- typed, and the shell commands are preceded by dollar signs ($):
360
-
361
- $ ls
362
- $ cat foo
363
- $ less bar
364
-
365
- The dollar signs are unnecessary in the above situation, and should not be
366
- included:
367
-
368
- ls
369
- cat foo
370
- less bar
371
-
372
- However, an exception is made when there is a need to distinguish between
373
- typed commands and command output, as in the following example:
374
-
375
- $ ls
376
- foo bar
377
- $ cat foo
378
- Hello world
379
- $ cat bar
380
- baz
381
-
382
- Rationale: it is easier to copy and paste and less noisy if the dollar signs
383
- are omitted when they are not needed. See
384
- <http://www.cirosantilli.com/markdown-styleguide/#dollar-signs-in-shell-code>
385
- for more information.
386
-
387
- ## MD018 - No space after hash on atx style header
388
-
389
- Tags: headers, atx, spaces
390
-
391
- Aliases: no-missing-space-atx
392
-
393
- This rule is triggered when spaces are missing after the hash characters
394
- in an atx style header:
395
-
396
- #Header 1
397
-
398
- ##Header 2
399
-
400
- To fix this, separate the header text from the hash character by a single
401
- space:
402
-
403
- # Header 1
404
-
405
- ## Header 2
406
-
407
- ## MD019 - Multiple spaces after hash on atx style header
408
-
409
- Tags: headers, atx, spaces
410
-
411
- Aliases: no-multiple-space-atx
412
-
413
- This rule is triggered when more than one space is used to separate the
414
- header text from the hash characters in an atx style header:
415
-
416
- # Header 1
417
-
418
- ## Header 2
419
-
420
- To fix this, separate the header text from the hash character by a single
421
- space:
422
-
423
- # Header 1
424
-
425
- ## Header 2
426
-
427
- ## MD020 - No space inside hashes on closed atx style header
428
-
429
- Tags: headers, atx_closed, spaces
430
-
431
- Aliases: no-missing-space-closed-atx
432
-
433
- This rule is triggered when spaces are missing inside the hash characters
434
- in a closed atx style header:
435
-
436
- #Header 1#
437
-
438
- ##Header 2##
439
-
440
- To fix this, separate the header text from the hash character by a single
441
- space:
442
-
443
- # Header 1 #
444
-
445
- ## Header 2 ##
446
-
447
- Note: this rule will fire if either side of the header is missing spaces.
448
-
449
- ## MD021 - Multiple spaces inside hashes on closed atx style header
450
-
451
- Tags: headers, atx_closed, spaces
452
-
453
- Aliases: no-multiple-space-closed-atx
454
-
455
- This rule is triggered when more than one space is used to separate the
456
- header text from the hash characters in a closed atx style header:
457
-
458
- # Header 1 #
459
-
460
- ## Header 2 ##
461
-
462
- To fix this, separate the header text from the hash character by a single
463
- space:
464
-
465
- # Header 1 #
466
-
467
- ## Header 2 ##
468
-
469
- Note: this rule will fire if either side of the header contains multiple
470
- spaces.
471
-
472
- ## MD022 - Headers should be surrounded by blank lines
473
-
474
- Tags: headers, blank_lines
475
-
476
- Aliases: blanks-around-headers
477
-
478
- This rule is triggered when headers (any style) are either not preceded or not
479
- followed by a blank line:
480
-
481
- # Header 1
482
- Some text
483
-
484
- Some more text
485
- ## Header 2
486
-
487
- To fix this, ensure that all headers have a blank line both before and after
488
- (except where the header is at the beginning or end of the document):
489
-
490
- # Header 1
491
-
492
- Some text
493
-
494
- Some more text
495
-
496
- ## Header 2
497
-
498
- Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
499
- not parse headers that don't have a blank line before, and will parse them as
500
- regular text.
501
-
502
- ## MD023 - Headers must start at the beginning of the line
503
-
504
- Tags: headers, spaces
505
-
506
- Aliases: header-start-left
507
-
508
- This rule is triggered when a header is indented by one or more spaces:
509
-
510
- Some text
511
-
512
- # Indented header
513
-
514
- To fix this, ensure that all headers start at the beginning of the line:
515
-
516
- Some text
517
-
518
- # Header
519
-
520
- Rationale: Headers that don't start at the beginning of the line will not be
521
- parsed as headers, and will instead appear as regular text.
522
-
523
- ## MD024 - Multiple headers with the same content
524
-
525
- Tags: headers
526
-
527
- Aliases: no-duplicate-header
528
-
529
- Parameters: allow_different_nesting (boolean; default false)
530
-
531
- This rule is triggered if there are multiple headers in the document that have
532
- the same text:
533
-
534
- # Some text
535
-
536
- ## Some text
537
-
538
- To fix this, ensure that the content of each header is different:
539
-
540
- # Some text
541
-
542
- ## Some more text
543
-
544
- Rationale: Some markdown parses generate anchors for headers based on the
545
- header name, and having headers with the same content can cause problems with
546
- this.
547
-
548
- If the parameter `allow_different_nesting` is set to `true`, header duplication
549
- under different nesting is allowed, like it usually happens in change logs:
550
-
551
- # Change log
552
-
553
- ## 2.0.0
554
-
555
- ### Bug fixes
556
-
557
- ### Features
558
-
559
- ## 1.0.0
560
-
561
- ### Bug fixes
562
-
563
- ## MD025 - Multiple top level headers in the same document
564
-
565
- Tags: headers
566
-
567
- Aliases: single-h1
568
-
569
- Parameters: level (number; default 1)
570
-
571
- This rule is triggered when a top level header is in use (the first line of
572
- the file is a h1 header), and more than one h1 header is in use in the
573
- document:
574
-
575
- # Top level header
576
-
577
- # Another top level header
578
-
579
- To fix, structure your document so that there is a single h1 header that is
580
- the title for the document, and all later headers are h2 or lower level
581
- headers:
582
-
583
- # Title
584
-
585
- ## Header
586
-
587
- ## Another header
588
-
589
- Rationale: A top level header is a h1 on the first line of the file, and
590
- serves as the title for the document. If this convention is in use, then there
591
- can not be more than one title for the document, and the entire document
592
- should be contained within this header.
593
-
594
- Note: The `level` parameter can be used to change the top level (ex: to h2) in
595
- cases where an h1 is added externally.
596
-
597
- ## MD026 - Trailing punctuation in header
598
-
599
- Tags: headers
600
-
601
- Aliases: no-trailing-punctuation
602
-
603
- Parameters: punctuation (string; default ".,;:!?")
604
-
605
- This rule is triggered on any header that has a punctuation character as the
606
- last character in the line:
607
-
608
- # This is a header.
609
-
610
- To fix this, remove any trailing punctuation:
611
-
612
- # This is a header
613
-
614
- Note: The punctuation parameter can be used to specify what characters class
615
- as punctuation at the end of the header. For example, you can set it to
616
- `'.,;:!'` to allow headers with question marks in them, such as might be used
617
- in an FAQ.
618
-
619
- ## MD027 - Multiple spaces after blockquote symbol
620
-
621
- Tags: blockquote, whitespace, indentation
622
-
623
- Aliases: no-multiple-space-blockquote
624
-
625
- This rule is triggered when blockquotes have more than one space after the
626
- blockquote (`>`) symbol:
627
-
628
- > This is a block quote with bad indentation
629
- > there should only be one.
630
-
631
- To fix, remove any extraneous space:
632
-
633
- > This is a blockquote with correct
634
- > indentation.
635
-
636
- ## MD028 - Blank line inside blockquote
637
-
638
- Tags: blockquote, whitespace
639
-
640
- Aliases: no-blanks-blockquote
641
-
642
- This rule is triggered when two blockquote blocks are separated by nothing
643
- except for a blank line:
644
-
645
- > This is a blockquote
646
- > which is immediately followed by
647
-
648
- > this blockquote. Unfortunately
649
- > In some parsers, these are treated as the same blockquote.
650
-
651
- To fix this, ensure that any blockquotes that are right next to each other
652
- have some text in between:
653
-
654
- > This is a blockquote.
655
-
656
- And Jimmy also said:
657
-
658
- > This too is a blockquote.
659
-
660
- Alternatively, if they are supposed to be the same quote, then add the
661
- blockquote symbol at the beginning of the blank line:
662
-
663
- > This is a blockquote.
664
- >
665
- > This is the same blockquote.
666
-
667
- Rationale: Some markdown parsers will treat two blockquotes separated by one
668
- or more blank lines as the same blockquote, while others will treat them as
669
- separate blockquotes.
670
-
671
- ## MD029 - Ordered list item prefix
672
-
673
- Tags: ol
674
-
675
- Aliases: ol-prefix
676
-
677
- Parameters: style ("one", "ordered"; default "one")
678
-
679
- This rule is triggered on ordered lists that do not either start with '1.' or
680
- do not have a prefix that increases in numerical order (depending on the
681
- configured style, which defaults to 'one').
682
-
683
- Example valid list if the style is configured as 'one':
684
-
685
- 1. Do this.
686
- 1. Do that.
687
- 1. Done.
688
-
689
- Example valid list if the style is configured as 'ordered':
690
-
691
- 1. Do this.
692
- 2. Do that.
693
- 3. Done.
694
-
695
- ## MD030 - Spaces after list markers
696
-
697
- Tags: ol, ul, whitespace
698
-
699
- Aliases: list-marker-space
700
-
701
- Parameters: ul_single, ol_single, ul_multi, ol_multi (number, default 1)
702
-
703
- This rule checks for the number of spaces between a list marker (e.g. '`-`',
704
- '`*`', '`+`' or '`1.`') and the text of the list item.
705
-
706
- The number of spaces checked for depends on the document style in use, but the
707
- default is 1 space after any list marker:
708
-
709
- * Foo
710
- * Bar
711
- * Baz
712
-
713
- 1. Foo
714
- 1. Bar
715
- 1. Baz
716
-
717
- 1. Foo
718
- * Bar
719
- 1. Baz
720
-
721
- A document style may change the number of spaces after unordered list items
722
- and ordered list items independently, as well as based on whether the content
723
- of every item in the list consists of a single paragraph, or multiple
724
- paragraphs (including sub-lists and code blocks).
725
-
726
- For example, the style guide at
727
- <http://www.cirosantilli.com/markdown-styleguide/#spaces-after-marker>
728
- specifies that 1 space after the list marker should be used if every item in
729
- the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
730
- and unordered lists respectively) if there are multiple paragraphs of content
731
- inside the list:
732
-
733
- * Foo
734
- * Bar
735
- * Baz
736
-
737
- vs.
738
-
739
- * Foo
740
-
741
- Second paragraph
742
-
743
- * Bar
744
-
745
- or
746
-
747
- 1. Foo
748
-
749
- Second paragraph
750
-
751
- 1. Bar
752
-
753
- To fix this, ensure the correct number of spaces are used after list marker
754
- for your selected document style.
755
-
756
- ## MD031 - Fenced code blocks should be surrounded by blank lines
757
-
758
- Tags: code, blank_lines
759
-
760
- Aliases: blanks-around-fences
761
-
762
- This rule is triggered when fenced code blocks are either not preceded or not
763
- followed by a blank line:
764
-
765
- Some text
766
- ```
767
- Code block
768
- ```
769
-
770
- ```
771
- Another code block
772
- ```
773
- Some more text
774
-
775
- To fix this, ensure that all fenced code blocks have a blank line both before
776
- and after (except where the block is at the beginning or end of the document):
777
-
778
- Some text
779
-
780
- ```
781
- Code block
782
- ```
783
-
784
- ```
785
- Another code block
786
- ```
787
-
788
- Some more text
789
-
790
- Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
791
- not parse fenced code blocks that don't have blank lines before and after them.
792
-
793
- ## MD032 - Lists should be surrounded by blank lines
794
-
795
- Tags: bullet, ul, ol, blank_lines
796
-
797
- Aliases: blanks-around-lists
798
-
799
- This rule is triggered when lists (of any kind) are either not preceded or not
800
- followed by a blank line:
801
-
802
- Some text
803
- * Some
804
- * List
805
-
806
- 1. Some
807
- 2. List
808
- Some text
809
-
810
- To fix this, ensure that all lists have a blank line both before and after
811
- (except where the block is at the beginning or end of the document):
812
-
813
- Some text
814
-
815
- * Some
816
- * List
817
-
818
- 1. Some
819
- 2. List
820
-
821
- Some text
822
-
823
- Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
824
- not parse lists that don't have blank lines before and after them.
825
-
826
- Note: List items without hanging indents are a violation of this rule; list
827
- items with hanging indents are okay:
828
-
829
- * This is
830
- not okay
831
-
832
- * This is
833
- okay
834
-
835
- ## MD033 - Inline HTML
836
-
837
- Tags: html
838
-
839
- Aliases: no-inline-html
840
-
841
- This rule is triggered whenever raw HTML is used in a markdown document:
842
-
843
- <h1>Inline HTML header</h1>
844
-
845
- To fix this, use 'pure' markdown instead of including raw HTML:
846
-
847
- # Markdown header
848
-
849
- Rationale: Raw HTML is allowed in markdown, but this rule is included for
850
- those who want their documents to only include "pure" markdown, or for those
851
- who are rendering markdown documents in something other than HTML.
852
-
853
- ## MD034 - Bare URL used
854
-
855
- Tags: links, url
856
-
857
- Aliases: no-bare-urls
858
-
859
- This rule is triggered whenever a URL is given that isn't surrounded by angle
860
- brackets:
861
-
862
- For more information, see http://www.example.com/.
863
-
864
- To fix this, add angle brackets around the URL:
865
-
866
- For more information, see <http://www.example.com/>.
867
-
868
- Rationale: Without angle brackets, the URL isn't converted into a link in many
869
- markdown parsers.
870
-
871
- Note: if you do want a bare URL without it being converted into a link,
872
- enclose it in a code block, otherwise in some markdown parsers it _will_ be
873
- converted:
874
-
875
- `http://www.example.com`
876
-
877
- ## MD035 - Horizontal rule style
878
-
879
- Tags: hr
880
-
881
- Aliases: hr-style
882
-
883
- Parameters: style ("consistent", "---", "***", or other string specifying the
884
- horizontal rule; default "consistent")
885
-
886
- This rule is triggered when inconsistent styles of horizontal rules are used
887
- in the document:
888
-
889
- ---
890
-
891
- - - -
892
-
893
- ***
894
-
895
- * * *
896
-
897
- ****
898
-
899
- To fix this, ensure any horizontal rules used in the document are consistent,
900
- or match the given style if the rule is so configured:
901
-
902
- ---
903
-
904
- ---
905
-
906
- Note: by default, this rule is configured to just require that all horizontal
907
- rules in the document are the same, and will trigger if any of the horizontal
908
- rules are different than the first one encountered in the document. If you
909
- want to configure the rule to match a specific style, the parameter given to
910
- the 'style' option is a string containing the exact horizontal rule text that
911
- is allowed.
912
-
913
- ## MD036 - Emphasis used instead of a header
914
-
915
- Tags: headers, emphasis
916
-
917
- Parameters: punctuation (string; default ".,;:!?")
918
-
919
- Aliases: no-emphasis-as-header
920
-
921
- This check looks for instances where emphasized (i.e. bold or italic) text is
922
- used to separate sections, where a header should be used instead:
923
-
924
- **My document**
925
-
926
- Lorem ipsum dolor sit amet...
927
-
928
- _Another section_
929
-
930
- Consectetur adipiscing elit, sed do eiusmod.
931
-
932
- To fix this, use markdown headers instead of emphasized text to denote
933
- sections:
934
-
935
- # My document
936
-
937
- Lorem ipsum dolor sit amet...
938
-
939
- ## Another section
940
-
941
- Consectetur adipiscing elit, sed do eiusmod.
942
-
943
- Note: this rule looks for single line paragraphs that consist entirely of
944
- emphasized text. It won't fire on emphasis used within regular text,
945
- multi-line emphasized paragraphs, and paragraphs ending in punctuation.
946
- Similarly to rule MD026, you can configure what characters are recognized as
947
- punctuation.
948
-
949
- ## MD037 - Spaces inside emphasis markers
950
-
951
- Tags: whitespace, emphasis
952
-
953
- Aliases: no-space-in-emphasis
954
-
955
- This rule is triggered when emphasis markers (bold, italic) are used, but they
956
- have spaces between the markers and the text:
957
-
958
- Here is some ** bold ** text.
959
-
960
- Here is some * italic * text.
961
-
962
- Here is some more __ bold __ text.
963
-
964
- Here is some more _ italic _ text.
965
-
966
- To fix this, remove the spaces around the emphasis markers:
967
-
968
- Here is some **bold** text.
969
-
970
- Here is some *italic* text.
971
-
972
- Here is some more __bold__ text.
973
-
974
- Here is some more _italic_ text.
975
-
976
- Rationale: Emphasis is only parsed as such when the asterisks/underscores
977
- aren't completely surrounded by spaces. This rule attempts to detect where
978
- they were surrounded by spaces, but it appears that emphasized text was
979
- intended by the author.
980
-
981
- ## MD038 - Spaces inside code span elements
982
-
983
- Tags: whitespace, code
984
-
985
- Aliases: no-space-in-code
986
-
987
- This rule is triggered on code span elements that have spaces right inside the
988
- backticks:
989
-
990
- ` some text `
991
-
992
- `some text `
993
-
994
- ` some text`
995
-
996
- To fix this, remove the spaces inside the codespan markers:
997
-
998
- `some text`
999
-
1000
- ## MD039 - Spaces inside link text
1001
-
1002
- Tags: whitespace, links
1003
-
1004
- Aliases: no-space-in-links
1005
-
1006
- This rule is triggered on links that have spaces surrounding the link text:
1007
-
1008
- [ a link ](http://www.example.com/)
1009
-
1010
- To fix this, remove the spaces surrounding the link text:
1011
-
1012
- [a link](http://www.example.com/)
1013
-
1014
- ## MD040 - Fenced code blocks should have a language specified
1015
-
1016
- Tags: code, language
1017
-
1018
- Aliases: fenced-code-language
1019
-
1020
- This rule is triggered when fenced code blocks are used, but a language isn't
1021
- specified:
1022
-
1023
- ```
1024
- #!/bin/bash
1025
- echo Hello world
1026
- ```
1027
-
1028
- To fix this, add a language specifier to the code block:
1029
-
1030
- ```bash
1031
- #!/bin/bash
1032
- echo Hello world
1033
- ```
1034
-
1035
- ## MD041 - First line in file should be a top level header
1036
-
1037
- Tags: headers
1038
-
1039
- Aliases: first-line-h1
1040
-
1041
- Parameters: level (number; default 1)
1042
-
1043
- This rule is triggered when the first line in the file isn't a top level (h1)
1044
- header:
1045
-
1046
- ```
1047
- This is a file without a header
1048
- ```
1049
-
1050
- To fix this, add a header to the top of your file:
1051
-
1052
- ```
1053
- # File with header
1054
-
1055
- This is a file with a top level header
1056
- ```
1057
-
1058
- Note: The `level` parameter can be used to change the top level (ex: to h2) in
1059
- cases where an h1 is added externally.
1060
-
1061
- ## MD046 - Code block style
1062
-
1063
- Tags: code
1064
-
1065
- Aliases: code-block-style
1066
-
1067
- Parameters: style ("fenced", "indented", "consistent", default "fenced")
1068
-
1069
- This rule is triggered when a different code block style is used than the
1070
- configured one. For example, in the default configuration this rule is triggered
1071
- for the following document:
1072
-
1073
- Some text.
1074
-
1075
- Code block
1076
-
1077
- Some more text.
1078
-
1079
- To fix this, used fenced code blocks:
1080
-
1081
- Some text.
1082
-
1083
- ```ruby
1084
- Code block
1085
- ```
1086
-
1087
- Some more text.
1088
-
1089
- The reverse is true if the rule is configured to use the `indented` style.