mirror of
https://github.com/DavidAnson/markdownlint.git
synced 2025-09-22 05:40:48 +02:00
Update MD054/link-image-style to split reference parameter into full/collapsed/shortcut parameters (fixes #918).
This commit is contained in:
David Anson
parent
4390715f4b
commit
063310e51a
21 changed files with 2583 additions and 80 deletions
47
doc/Rules.md
47
doc/Rules.md
|
|
@ -2234,18 +2234,21 @@ Aliases: `link-image-style`
|
|||
Parameters:
|
||||
|
||||
- `autolink`: Allow autolinks (`boolean`, default `true`)
|
||||
- `collapsed`: Allow collapsed reference links and images (`boolean`, default
|
||||
`true`)
|
||||
- `full`: Allow full reference links and images (`boolean`, default `true`)
|
||||
- `inline`: Allow inline links and images (`boolean`, default `true`)
|
||||
- `reference`: Allow reference links and images (`boolean`, default `true`)
|
||||
- `shortcut`: Allow shortcut reference links and images (`boolean`, default
|
||||
`true`)
|
||||
|
||||
Fixable: Some violations can be fixed by tooling
|
||||
|
||||
Links and images in Markdown can provide the link destination or image source at
|
||||
the time of use or can use a label to reference a definition elsewhere in the
|
||||
document. The reference format is convenient for keeping paragraph text
|
||||
clutter-free and makes it easy to reuse the same URL in multiple places.
|
||||
document. The three reference formats are convenient for keeping paragraph text
|
||||
clutter-free and make it easy to reuse the same URL in multiple places.
|
||||
|
||||
By default, this rule allows all link/image styles. It is possible to disable
|
||||
one or more of those styles.
|
||||
By default, this rule allows all link/image styles.
|
||||
|
||||
Setting the `autolink` parameter to `false` disables autolinks:
|
||||
|
||||
|
|
@ -2261,20 +2264,34 @@ Setting the `inline` parameter to `false` disables inline links and images:
|
|||
|
||||
```
|
||||
|
||||
Setting the `reference` parameter to `false` disables full, collapsed, and
|
||||
shortcut reference links and images:
|
||||
Setting the `full` parameter to `false` disables full reference links and
|
||||
images:
|
||||
|
||||
```markdown
|
||||
[link][url]
|
||||
|
||||
[url][]
|
||||
|
||||
[url]
|
||||
|
||||
![image][url]
|
||||
|
||||
[url]: https://example.com
|
||||
```
|
||||
|
||||
Setting the `collapsed` parameter to `false` disables collapsed reference links
|
||||
and images:
|
||||
|
||||
```markdown
|
||||
[url][]
|
||||
|
||||
![url][]
|
||||
|
||||
[url]: https://example.com
|
||||
```
|
||||
|
||||
Setting the `shortcut` parameter to `false` disables shortcut reference links
|
||||
and images:
|
||||
|
||||
```markdown
|
||||
[url]
|
||||
|
||||
![url]
|
||||
|
||||
[url]: https://example.com
|
||||
|
|
@ -2284,15 +2301,15 @@ To fix violations of this rule, change the link or image to use an allowed
|
|||
style. This rule can automatically fix violations when a link or image can be
|
||||
converted to the `inline` style (preferred) or a link can be converted to the
|
||||
`autolink` style (which does not support images and must be an absolute URL).
|
||||
This rule does not fix scenarios that require converting a link or image to the
|
||||
`reference` style because that involves naming the reference and knowing where
|
||||
in the document to insert it.
|
||||
This rule does *not* fix scenarios that require converting a link or image to
|
||||
the `full`, `collapsed`, or `shortcut` reference styles because that involves
|
||||
naming the reference and determining where to insert it in the document.
|
||||
|
||||
Rationale: Consistent formatting makes it easier to understand a document.
|
||||
Autolinks are concise, but appear as URLs which can be long and confusing.
|
||||
Inline links and images can include descriptive text, but take up more space in
|
||||
Markdown form. Reference links and images can be easier to read and manipulate
|
||||
in Markdown form, but require editing two locations.
|
||||
in Markdown form, but require a separate link reference definition.
|
||||
|
||||
<!-- markdownlint-configure-file {
|
||||
"no-inline-html": {
|
||||
|
|
|
|||
47
doc/md054.md
47
doc/md054.md
|
|
@ -7,18 +7,21 @@ Aliases: `link-image-style`
|
|||
Parameters:
|
||||
|
||||
- `autolink`: Allow autolinks (`boolean`, default `true`)
|
||||
- `collapsed`: Allow collapsed reference links and images (`boolean`, default
|
||||
`true`)
|
||||
- `full`: Allow full reference links and images (`boolean`, default `true`)
|
||||
- `inline`: Allow inline links and images (`boolean`, default `true`)
|
||||
- `reference`: Allow reference links and images (`boolean`, default `true`)
|
||||
- `shortcut`: Allow shortcut reference links and images (`boolean`, default
|
||||
`true`)
|
||||
|
||||
Fixable: Some violations can be fixed by tooling
|
||||
|
||||
Links and images in Markdown can provide the link destination or image source at
|
||||
the time of use or can use a label to reference a definition elsewhere in the
|
||||
document. The reference format is convenient for keeping paragraph text
|
||||
clutter-free and makes it easy to reuse the same URL in multiple places.
|
||||
document. The three reference formats are convenient for keeping paragraph text
|
||||
clutter-free and make it easy to reuse the same URL in multiple places.
|
||||
|
||||
By default, this rule allows all link/image styles. It is possible to disable
|
||||
one or more of those styles.
|
||||
By default, this rule allows all link/image styles.
|
||||
|
||||
Setting the `autolink` parameter to `false` disables autolinks:
|
||||
|
||||
|
|
@ -34,20 +37,34 @@ Setting the `inline` parameter to `false` disables inline links and images:
|
|||
|
||||
```
|
||||
|
||||
Setting the `reference` parameter to `false` disables full, collapsed, and
|
||||
shortcut reference links and images:
|
||||
Setting the `full` parameter to `false` disables full reference links and
|
||||
images:
|
||||
|
||||
```markdown
|
||||
[link][url]
|
||||
|
||||
[url][]
|
||||
|
||||
[url]
|
||||
|
||||
![image][url]
|
||||
|
||||
[url]: https://example.com
|
||||
```
|
||||
|
||||
Setting the `collapsed` parameter to `false` disables collapsed reference links
|
||||
and images:
|
||||
|
||||
```markdown
|
||||
[url][]
|
||||
|
||||
![url][]
|
||||
|
||||
[url]: https://example.com
|
||||
```
|
||||
|
||||
Setting the `shortcut` parameter to `false` disables shortcut reference links
|
||||
and images:
|
||||
|
||||
```markdown
|
||||
[url]
|
||||
|
||||
![url]
|
||||
|
||||
[url]: https://example.com
|
||||
|
|
@ -57,12 +74,12 @@ To fix violations of this rule, change the link or image to use an allowed
|
|||
style. This rule can automatically fix violations when a link or image can be
|
||||
converted to the `inline` style (preferred) or a link can be converted to the
|
||||
`autolink` style (which does not support images and must be an absolute URL).
|
||||
This rule does not fix scenarios that require converting a link or image to the
|
||||
`reference` style because that involves naming the reference and knowing where
|
||||
in the document to insert it.
|
||||
This rule does *not* fix scenarios that require converting a link or image to
|
||||
the `full`, `collapsed`, or `shortcut` reference styles because that involves
|
||||
naming the reference and determining where to insert it in the document.
|
||||
|
||||
Rationale: Consistent formatting makes it easier to understand a document.
|
||||
Autolinks are concise, but appear as URLs which can be long and confusing.
|
||||
Inline links and images can include descriptive text, but take up more space in
|
||||
Markdown form. Reference links and images can be easier to read and manipulate
|
||||
in Markdown form, but require editing two locations.
|
||||
in Markdown form, but require a separate link reference definition.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue