From b4366409187e28e91ed5863e19153358e2af0e9c Mon Sep 17 00:00:00 2001 From: David Anson Date: Sun, 7 May 2017 12:48:04 -0700 Subject: [PATCH] Add short links to each rule in Rules.md, update README.md to use them (fixes #54). --- .markdownlint.json | 8 ++++ README.md | 80 +++++++++++++++++++-------------------- doc/Rules.md | 80 +++++++++++++++++++++++++++++++++++++++ lib/markdownlint.js | 5 ++- test/markdownlint-test.js | 3 +- 5 files changed, 133 insertions(+), 43 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..8382174a --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,8 @@ +{ + "line-length": false, + "no-inline-html": { + "allowed_elements": [ + "a" + ] + } +} diff --git a/README.md b/README.md index 6ebeece0..3815fc94 100644 --- a/README.md +++ b/README.md @@ -45,46 +45,46 @@ playground for learning and exploring. ## Rules / Aliases -* **MD001** *header-increment* - Header levels should only increment by one level at a time -* **MD002** *first-header-h1* - First header should be a top level header -* **MD003** *header-style* - Header style -* **MD004** *ul-style* - Unordered list style -* **MD005** *list-indent* - Inconsistent indentation for list items at the same level -* **MD006** *ul-start-left* - Consider starting bulleted lists at the beginning of the line -* **MD007** *ul-indent* - Unordered list indentation -* **MD009** *no-trailing-spaces* - Trailing spaces -* **MD010** *no-hard-tabs* - Hard tabs -* **MD011** *no-reversed-links* - Reversed link syntax -* **MD012** *no-multiple-blanks* - Multiple consecutive blank lines -* **MD013** *line-length* - Line length -* **MD014** *commands-show-output* - Dollar signs used before commands without showing output -* **MD018** *no-missing-space-atx* - No space after hash on atx style header -* **MD019** *no-multiple-space-atx* - Multiple spaces after hash on atx style header -* **MD020** *no-missing-space-closed-atx* - No space inside hashes on closed atx style header -* **MD021** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style header -* **MD022** *blanks-around-headers* - Headers should be surrounded by blank lines -* **MD023** *header-start-left* - Headers must start at the beginning of the line -* **MD024** *no-duplicate-header* - Multiple headers with the same content -* **MD025** *single-h1* - Multiple top level headers in the same document -* **MD026** *no-trailing-punctuation* - Trailing punctuation in header -* **MD027** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol -* **MD028** *no-blanks-blockquote* - Blank line inside blockquote -* **MD029** *ol-prefix* - Ordered list item prefix -* **MD030** *list-marker-space* - Spaces after list markers -* **MD031** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines -* **MD032** *blanks-around-lists* - Lists should be surrounded by blank lines -* **MD033** *no-inline-html* - Inline HTML -* **MD034** *no-bare-urls* - Bare URL used -* **MD035** *hr-style* - Horizontal rule style -* **MD036** *no-emphasis-as-header* - Emphasis used instead of a header -* **MD037** *no-space-in-emphasis* - Spaces inside emphasis markers -* **MD038** *no-space-in-code* - Spaces inside code span elements -* **MD039** *no-space-in-links* - Spaces inside link text -* **MD040** *fenced-code-language* - Fenced code blocks should have a language specified -* **MD041** *first-line-h1* - First line in file should be a top level header -* **MD042** *no-empty-links* - No empty links -* **MD043** *required-headers* - Required header structure -* **MD044** *proper-names* - Proper names should have the correct capitalization +* **[MD001](doc/Rules.md#md001)** *header-increment* - Header levels should only increment by one level at a time +* **[MD002](doc/Rules.md#md002)** *first-header-h1* - First header should be a top level header +* **[MD003](doc/Rules.md#md003)** *header-style* - Header style +* **[MD004](doc/Rules.md#md004)** *ul-style* - Unordered list style +* **[MD005](doc/Rules.md#md005)** *list-indent* - Inconsistent indentation for list items at the same level +* **[MD006](doc/Rules.md#md006)** *ul-start-left* - Consider starting bulleted lists at the beginning of the line +* **[MD007](doc/Rules.md#md007)** *ul-indent* - Unordered list indentation +* **[MD009](doc/Rules.md#md009)** *no-trailing-spaces* - Trailing spaces +* **[MD010](doc/Rules.md#md010)** *no-hard-tabs* - Hard tabs +* **[MD011](doc/Rules.md#md011)** *no-reversed-links* - Reversed link syntax +* **[MD012](doc/Rules.md#md012)** *no-multiple-blanks* - Multiple consecutive blank lines +* **[MD013](doc/Rules.md#md013)** *line-length* - Line length +* **[MD014](doc/Rules.md#md014)** *commands-show-output* - Dollar signs used before commands without showing output +* **[MD018](doc/Rules.md#md018)** *no-missing-space-atx* - No space after hash on atx style header +* **[MD019](doc/Rules.md#md019)** *no-multiple-space-atx* - Multiple spaces after hash on atx style header +* **[MD020](doc/Rules.md#md020)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style header +* **[MD021](doc/Rules.md#md021)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style header +* **[MD022](doc/Rules.md#md022)** *blanks-around-headers* - Headers should be surrounded by blank lines +* **[MD023](doc/Rules.md#md023)** *header-start-left* - Headers must start at the beginning of the line +* **[MD024](doc/Rules.md#md024)** *no-duplicate-header* - Multiple headers with the same content +* **[MD025](doc/Rules.md#md025)** *single-h1* - Multiple top level headers in the same document +* **[MD026](doc/Rules.md#md026)** *no-trailing-punctuation* - Trailing punctuation in header +* **[MD027](doc/Rules.md#md027)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol +* **[MD028](doc/Rules.md#md028)** *no-blanks-blockquote* - Blank line inside blockquote +* **[MD029](doc/Rules.md#md029)** *ol-prefix* - Ordered list item prefix +* **[MD030](doc/Rules.md#md030)** *list-marker-space* - Spaces after list markers +* **[MD031](doc/Rules.md#md031)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines +* **[MD032](doc/Rules.md#md032)** *blanks-around-lists* - Lists should be surrounded by blank lines +* **[MD033](doc/Rules.md#md033)** *no-inline-html* - Inline HTML +* **[MD034](doc/Rules.md#md034)** *no-bare-urls* - Bare URL used +* **[MD035](doc/Rules.md#md035)** *hr-style* - Horizontal rule style +* **[MD036](doc/Rules.md#md036)** *no-emphasis-as-header* - Emphasis used instead of a header +* **[MD037](doc/Rules.md#md037)** *no-space-in-emphasis* - Spaces inside emphasis markers +* **[MD038](doc/Rules.md#md038)** *no-space-in-code* - Spaces inside code span elements +* **[MD039](doc/Rules.md#md039)** *no-space-in-links* - Spaces inside link text +* **[MD040](doc/Rules.md#md040)** *fenced-code-language* - Fenced code blocks should have a language specified +* **[MD041](doc/Rules.md#md041)** *first-line-h1* - First line in file should be a top level header +* **[MD042](doc/Rules.md#md042)** *no-empty-links* - No empty links +* **[MD043](doc/Rules.md#md043)** *required-headers* - Required header structure +* **[MD044](doc/Rules.md#md044)** *proper-names* - Proper names should have the correct capitalization See [Rules.md](doc/Rules.md) for more details. diff --git a/doc/Rules.md b/doc/Rules.md index 345b7a0e..9bc856bd 100644 --- a/doc/Rules.md +++ b/doc/Rules.md @@ -4,6 +4,8 @@ This document contains a description of all rules, what they are checking for, as well as an examples of documents that break the rule and corrected versions of the examples. + + ## MD001 - Header levels should only increment by one level at a time Tags: headers @@ -34,6 +36,8 @@ level at a time: ### Another Header 3 + + ## MD002 - First header should be a top level header Tags: headers @@ -57,6 +61,8 @@ The first header in the document should be a h1 header: Note: The `level` parameter can be used to change the top level (ex: to h2) in cases where an h1 is added externally. + + ## MD003 - Header style Tags: headers @@ -97,6 +103,8 @@ Note: the configured header style can be a specific style to use (atx, atx_closed, setext, setext_with_atx, setext_with_atx_closed), or simply require that the usage be consistent within the document. + + ## MD004 - Unordered list style Tags: bullet, ul @@ -134,6 +142,8 @@ indent uses asterisk, the middle indent uses plus, and the inner-most indent use * Item 4 + Item 5 + + ## MD005 - Inconsistent indentation for list items at the same level Tags: bullet, ul, indentation @@ -156,6 +166,8 @@ for the list to fix it: * Nested Item 2 * Nested Item 3 + + ## MD006 - Consider starting bulleted lists at the beginning of the line Tags: bullet, ul, indentation @@ -193,6 +205,8 @@ instead. - List item 1. List item + + ## MD007 - Unordered list indentation Tags: bullet, ul, indentation @@ -232,6 +246,8 @@ Note: This rule applies to a sublist only if its parent lists are all also unordered (otherwise, extra indentation of ordered lists interferes with the rule). + + ## MD009 - Trailing spaces Tags: whitespace @@ -252,6 +268,8 @@ effect - you can't insert a br element with just a single trailing space, so if you set br_spaces to 1, the exception will be disabled, just as if it was set to the default of 0. + + ## MD010 - Hard tabs Tags: whitespace, hard_tab @@ -280,6 +298,8 @@ You have the option to exclude this rule for code blocks. To do so, set the `code_blocks` parameter to `false`. Code blocks are included by default since handling of tabs by tools is often inconsistent (ex: using 4 vs. 8 spaces). + + ## MD011 - Reversed link syntax Tags: links @@ -300,6 +320,8 @@ Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style footn For (example)[^1] + + ## MD012 - Multiple consecutive blank lines Tags: whitespace, blank_lines @@ -328,6 +350,8 @@ lines inside code blocks. Note: The `maximum` parameter can be used to configure the maximum number of consecutive blank lines. + + ## MD013 - Line length Tags: line_length @@ -351,6 +375,8 @@ Code blocks are included in this rule by default since it is often a requirement for document readability, and tentatively compatible with code rules. Still, some languages do not lend themselves to short lines. + + ## MD014 - Dollar signs used before commands without showing output Tags: code @@ -386,6 +412,8 @@ are omitted when they are not needed. See for more information. + + ## MD018 - No space after hash on atx style header Tags: headers, atx, spaces @@ -406,6 +434,8 @@ space: ## Header 2 + + ## MD019 - Multiple spaces after hash on atx style header Tags: headers, atx, spaces @@ -426,6 +456,8 @@ space: ## Header 2 + + ## MD020 - No space inside hashes on closed atx style header Tags: headers, atx_closed, spaces @@ -448,6 +480,8 @@ space: Note: this rule will fire if either side of the header is missing spaces. + + ## MD021 - Multiple spaces inside hashes on closed atx style header Tags: headers, atx_closed, spaces @@ -471,6 +505,8 @@ space: Note: this rule will fire if either side of the header contains multiple spaces. + + ## MD022 - Headers should be surrounded by blank lines Tags: headers, blank_lines @@ -501,6 +537,8 @@ Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text. + + ## MD023 - Headers must start at the beginning of the line Tags: headers, spaces @@ -522,6 +560,8 @@ To fix this, ensure that all headers start at the beginning of the line: Rationale: Headers that don't start at the beginning of the line will not be parsed as headers, and will instead appear as regular text. + + ## MD024 - Multiple headers with the same content Tags: headers @@ -545,6 +585,8 @@ Rationale: Some markdown parses generate anchors for headers based on the header name, and having headers with the same content can cause problems with this. + + ## MD025 - Multiple top level headers in the same document Tags: headers @@ -579,6 +621,8 @@ should be contained within this header. Note: The `level` parameter can be used to change the top level (ex: to h2) in cases where an h1 is added externally. + + ## MD026 - Trailing punctuation in header Tags: headers @@ -601,6 +645,8 @@ as punctuation at the end of the header. For example, you can set it to `".,;:!"` to allow headers with question marks in them, such as might be used in an FAQ. + + ## MD027 - Multiple spaces after blockquote symbol Tags: blockquote, whitespace, indentation @@ -618,6 +664,8 @@ To fix, remove any extraneous space: > This is a blockquote with correct > indentation. + + ## MD028 - Blank line inside blockquote Tags: blockquote, whitespace @@ -653,6 +701,8 @@ Rationale: Some markdown parsers will treat two blockquotes separated by one or more blank lines as the same blockquote, while others will treat them as separate blockquotes. + + ## MD029 - Ordered list item prefix Tags: ol @@ -677,6 +727,8 @@ Example valid list if the style is configured as 'ordered': 2. Do that. 3. Done. + + ## MD030 - Spaces after list markers Tags: ol, ul, whitespace @@ -738,6 +790,8 @@ inside the list: To fix this, ensure the correct number of spaces are used after list marker for your selected document style. + + ## MD031 - Fenced code blocks should be surrounded by blank lines Tags: code, blank_lines @@ -775,6 +829,8 @@ and after (except where the block is at the beginning or end of the document): Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse fenced code blocks that don't have blank lines before and after them. + + ## MD032 - Lists should be surrounded by blank lines Tags: bullet, ul, ol, blank_lines @@ -817,6 +873,8 @@ items with hanging indents are okay: * This is okay + + ## MD033 - Inline HTML Tags: html @@ -839,6 +897,8 @@ who are rendering markdown documents in something other than HTML. Note: To allow specific HTML elements, use the 'allowed_elements' parameter. + + ## MD034 - Bare URL used Tags: links, url @@ -863,6 +923,8 @@ converted: `http://www.example.com` + + ## MD035 - Horizontal rule style Tags: hr @@ -899,6 +961,8 @@ want to configure the rule to match a specific style, the parameter given to the 'style' option is a string containing the exact horizontal rule text that is allowed. + + ## MD036 - Emphasis used instead of a header Tags: headers, emphasis @@ -935,6 +999,8 @@ multi-line emphasized paragraphs, and paragraphs ending in punctuation. Similarly to rule MD026, you can configure what characters are recognized as punctuation. + + ## MD037 - Spaces inside emphasis markers Tags: whitespace, emphasis @@ -967,6 +1033,8 @@ aren't completely surrounded by spaces. This rule attempts to detect where they were surrounded by spaces, but it appears that emphasized text was intended by the author. + + ## MD038 - Spaces inside code span elements Tags: whitespace, code @@ -991,6 +1059,8 @@ markers from an embedded backtick: `` ` embedded backtick`` + + ## MD039 - Spaces inside link text Tags: whitespace, links @@ -1005,6 +1075,8 @@ To fix this, remove the spaces surrounding the link text: [a link](http://www.example.com/) + + ## MD040 - Fenced code blocks should have a language specified Tags: code, language @@ -1026,6 +1098,8 @@ To fix this, add a language specifier to the code block: echo Hello world ``` + + ## MD041 - First line in file should be a top level header Tags: headers @@ -1054,6 +1128,8 @@ violation. To use a different property name in front matter, specify the text of a regular expression via the `front_matter_title` parameter. To disable the use of front matter by this rule, specify `""` for `front_matter_title`. + + ## MD042 - No empty links Tags: links @@ -1076,6 +1152,8 @@ But non-empty fragments will not: [a valid fragment](#fragment) + + ## MD043 - Required header structure Tags: headers @@ -1127,6 +1205,8 @@ problematic header (otherwise, it outputs the last line number of the file). Note that while the `headers` parameter uses the "## Text" ATX header style for simplicity, a file may use any supported header style. + + ## MD044 - Proper names should have the correct capitalization Tags: spelling diff --git a/lib/markdownlint.js b/lib/markdownlint.js index 4f8b4cab..c714402b 100644 --- a/lib/markdownlint.js +++ b/lib/markdownlint.js @@ -13,8 +13,9 @@ rules.forEach(function forRule(rule) { allRuleNames.push(rule.name); ruleNameToRule[rule.name] = rule; // The following is useful for updating README.md - // console.log("* **" + rule.name + "** *" + - // rule.aliases.join(", ") + "* - " + rule.desc); + // console.log( + // "* **[" + rule.name + "](doc/Rules.md#" + rule.name.toLowerCase() + + // ")** *" + rule.aliases.join(", ") + "* - " + rule.desc); rule.tags.forEach(function forTag(tag) { var tagUpper = tag.toUpperCase(); var ruleNames = idUpperToRuleNames[tagUpper] || []; diff --git a/test/markdownlint-test.js b/test/markdownlint-test.js index 1e61314a..f73cbe55 100644 --- a/test/markdownlint-test.js +++ b/test/markdownlint-test.js @@ -968,7 +968,8 @@ module.exports.readme = function readme(test) { test.ok(rule, "Missing rule implementation for " + token.content + "."); if (rule) { - var expected = "**" + rule.name + "** *" + + var expected = "**[" + rule.name + "](doc/Rules.md#" + + rule.name.toLowerCase() + ")** *" + rule.aliases.join(", ") + "* - " + rule.desc; test.equal(token.content, expected, "Rule mismatch."); }