Skip to content

Commit cfaad2e

Browse files
committed
fix(md077): keep the strict-flavor minimum as a floor under a configured indent
A configured indent replaced the requirement outright, including under a flavor that requires strict list indentation. `indent = 2` with `--flavor mkdocs` therefore lowered the requirement below the 4-space minimum Python-Markdown needs, so a document that rendered correctly was reported as over-indented and `fix` rewrote it into a form the renderer no longer reads as part of the list item. The minimum is now a floor a configured indent may raise but not lower, and the clamp is scoped to that flavor: under the standard flavor `indent = 2` still means 2. Which setting produced the requirement also decides what the message may claim. A configured indent above the content column is a house style, not a structural break, so it no longer reports that content "needs N spaces of indentation to remain part of the list" for content that is still part of the list. The structural and MkDocs wordings are unchanged for the cases that warrant them. The documented behavior of `indent` was wrong in the same area: it said content below the requirement is flagged under the same rules as the default, which is not true of tight lazy continuation. `style` still decides which lines are checked, and the two limits on the value are documented.
1 parent 1ac97a3 commit cfaad2e

2 files changed

Lines changed: 155 additions & 6 deletions

File tree

‎docs/md077.md‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -236,9 +236,9 @@ to the content column.
236236
style = "any"
237237

238238
# Fixed continuation indent relative to each item's marker, e.g. 4 for
239-
# MkDocs-style documents. When set, this overrides the content-column-derived
240-
# requirement (including the MkDocs flavor's 4-space minimum). Unset (None)
241-
# keeps the default content-column behavior.
239+
# MkDocs-style documents. When set, this replaces the content-column-derived
240+
# requirement; under the MkDocs flavor it can only raise the 4-space minimum,
241+
# never lower it. Must be 1 or greater. Unset keeps the content-column default.
242242
# indent = 4
243243
```
244244

@@ -266,8 +266,25 @@ content at 4 spaces, and a nested item (marker at column 2) requires it at 6:
266266
that continues 4 spaces past the nested marker
267267
```
268268

269-
Continuation content below the fixed requirement is flagged and fixed up to it
270-
(the same rules for blank-line escapes and over-indentation still apply).
269+
`indent` changes *what* the requirement is, not *when* it is enforced, so the
270+
`style` setting still decides which lines are checked against it:
271+
272+
- Content after a blank line below the requirement is flagged and fixed up to
273+
it, under either style.
274+
- Content indented past the requirement is flagged and snapped back, under
275+
either style.
276+
- A *tight* continuation line (no blank line above it) below the requirement is
277+
CommonMark lazy continuation, so `style = "any"` still accepts it. Set
278+
`style = "aligned"` to have those raised to the requirement as well.
279+
280+
Two limits apply to the value itself. `indent = 0` is rejected, with a warning
281+
and a fallback to MD077's defaults for the run: content at the marker's own
282+
column is not continuation at all, it ends the list item. And under a flavor
283+
that requires strict list indentation (MkDocs), the 4-space minimum acts as a
284+
floor a configured indent may raise but not lower, since below it the renderer
285+
stops reading the line as part of the item. `indent = 2` under
286+
`--flavor mkdocs` therefore still requires 4, while the same setting under the
287+
standard flavor requires 2, as written.
271288

272289
### `style = "aligned"`
273290

‎src/rules/md077_list_continuation_indent.rs‎

Lines changed: 133 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -651,7 +651,15 @@ impl Rule for MD077ListContinuationIndent {
651651
.iter()
652652
.enumerate()
653653
.map(|(item_idx, &(item_line, marker_col, content_col, task_col))| {
654+
// A configured indent replaces the content column, but under a
655+
// flavor that requires strict list indentation it may only raise
656+
// the 4-space minimum. That minimum is a compatibility floor
657+
// rather than a style default: below it the renderer stops
658+
// treating the line as continuation, so honoring a smaller
659+
// configured value would make `fix` rewrite documents into a
660+
// form the flavor's renderer no longer reads as part of the item.
654661
let required = match self.config.indent {
662+
Some(indent) if strict_indent => (marker_col + indent).max(4),
655663
Some(indent) => marker_col + indent,
656664
None if strict_indent => content_col.max(4),
657665
None => content_col,
@@ -748,6 +756,12 @@ impl Rule for MD077ListContinuationIndent {
748756
// input (a safe false negative). Real nested items never reach the
749757
// callback (the walk handles them via `saw_nested`).
750758
let has_latent_structure = aligned && Self::item_range_has_latent_structure(ctx, item_line, range_end);
759+
// Which setting produced `required` decides what the message may
760+
// claim. The content column carries a structural consequence (below
761+
// it the content leaves the item) and the strict-flavor minimum
762+
// carries a renderer requirement, but a configured indent above
763+
// both is a house style, so it is reported as one.
764+
let from_configured_indent = self.config.indent.is_some_and(|indent| marker_col + indent == required);
751765
Self::walk_item_continuation(ctx, item_line, range_end, marker_col, |line| {
752766
let actual = line.actual;
753767
let under_indented = actual < required;
@@ -767,7 +781,12 @@ impl Rule for MD077ListContinuationIndent {
767781
&& !confirmed_structure;
768782
if (loose_escape || aligned_tight) && flagged_lines.insert(line.line_num) {
769783
let message = if line.saw_blank {
770-
if strict_indent {
784+
if from_configured_indent {
785+
format!(
786+
"Content after blank line in list item needs {required} spaces of \
787+
indentation to match the configured indent (found {actual})",
788+
)
789+
} else if strict_indent {
771790
format!(
772791
"Content inside list item needs {required} spaces of indentation \
773792
for MkDocs compatibility (found {actual})",
@@ -2932,6 +2951,119 @@ mod tests {
29322951
);
29332952
}
29342953

2954+
/// A rule configured through the real `[MD077]` config path.
2955+
fn rule_with(settings: &[(&str, toml::Value)]) -> Box<dyn Rule> {
2956+
let mut config = crate::config::Config::default();
2957+
let mut rule_config = crate::config::RuleConfig::default();
2958+
for (key, value) in settings {
2959+
rule_config.values.insert((*key).to_string(), value.clone());
2960+
}
2961+
config.rules.insert("MD077".to_string(), rule_config);
2962+
MD077ListContinuationIndent::from_config(&config)
2963+
}
2964+
2965+
#[test]
2966+
fn configured_indent_cannot_lower_the_strict_flavor_minimum() {
2967+
// The MkDocs 4-space minimum is what the renderer needs to read a line
2968+
// as part of the item, so `indent = 2` may not pull it down to 2 - that
2969+
// would have `fix` rewrite a rendering document into a broken one.
2970+
let rule = rule_with(&[("indent", toml::Value::Integer(2))]);
2971+
2972+
let two = LintContext::new("- item\n\n wrap\n", MarkdownFlavor::MkDocs, None);
2973+
let warnings = rule.check(&two).unwrap();
2974+
assert_eq!(warnings.len(), 1, "2 spaces is below the MkDocs minimum: {warnings:?}");
2975+
assert!(
2976+
warnings[0].message.contains("needs 4 spaces") && warnings[0].message.contains("MkDocs"),
2977+
"the requirement comes from MkDocs, so the message must say so: {}",
2978+
warnings[0].message
2979+
);
2980+
assert_eq!(rule.fix(&two).unwrap(), "- item\n\n wrap\n");
2981+
2982+
// Control: a document already at the minimum is left alone.
2983+
let four = LintContext::new("- item\n\n wrap\n", MarkdownFlavor::MkDocs, None);
2984+
assert!(rule.check(&four).unwrap().is_empty());
2985+
2986+
// Control: the clamp is scoped to the strict flavor. Under the standard
2987+
// flavor the same setting means exactly what it says, and 4 is then an
2988+
// over-indent to be snapped back to 2.
2989+
let standard = LintContext::new("- item\n\n wrap\n", MarkdownFlavor::Standard, None);
2990+
assert_eq!(rule.check(&standard).unwrap().len(), 1);
2991+
assert_eq!(rule.fix(&standard).unwrap(), "- item\n\n wrap\n");
2992+
}
2993+
2994+
#[test]
2995+
fn configured_indent_can_raise_the_strict_flavor_minimum() {
2996+
// The clamp is a floor, not a fixed value: above 4 the configured indent
2997+
// still governs under the MkDocs flavor.
2998+
let rule = rule_with(&[("indent", toml::Value::Integer(6))]);
2999+
let ctx = LintContext::new("- item\n\n wrap\n", MarkdownFlavor::MkDocs, None);
3000+
let warnings = rule.check(&ctx).unwrap();
3001+
assert_eq!(warnings.len(), 1);
3002+
assert!(
3003+
warnings[0].message.contains("needs 6 spaces"),
3004+
"configured 6 must win over the 4-space floor: {}",
3005+
warnings[0].message
3006+
);
3007+
assert_eq!(rule.fix(&ctx).unwrap(), "- item\n\n wrap\n");
3008+
}
3009+
3010+
#[test]
3011+
fn configured_indent_message_does_not_claim_a_structural_consequence() {
3012+
// Two spaces under a `- ` marker keeps the content in the list item, so
3013+
// a message blaming list membership would be false. The requirement is
3014+
// the configured one and the message has to say which.
3015+
let rule = rule_with(&[("indent", toml::Value::Integer(4))]);
3016+
let ctx = LintContext::new("- item\n\n wrap\n", MarkdownFlavor::Standard, None);
3017+
let warnings = rule.check(&ctx).unwrap();
3018+
assert_eq!(warnings.len(), 1);
3019+
assert!(
3020+
warnings[0].message.contains("match the configured indent"),
3021+
"expected the configured-indent wording, got: {}",
3022+
warnings[0].message
3023+
);
3024+
assert!(
3025+
!warnings[0].message.contains("remain part of the list"),
3026+
"the content does remain part of the list here: {}",
3027+
warnings[0].message
3028+
);
3029+
3030+
// Control: the default rule reports the same document as clean, which is
3031+
// what makes the structural claim wrong above.
3032+
assert!(check("- item\n\n wrap\n").is_empty());
3033+
3034+
// Control: content that really would escape the item still gets the
3035+
// structural message, so the wording was narrowed and not replaced.
3036+
let escaping = check("- item\n\n wrap\n");
3037+
assert_eq!(escaping.len(), 1);
3038+
assert!(
3039+
escaping[0].message.contains("remain part of the list"),
3040+
"unconfigured under-indent keeps its structural message, got: {}",
3041+
escaping[0].message
3042+
);
3043+
}
3044+
3045+
#[test]
3046+
fn configured_indent_leaves_tight_lazy_continuation_to_style() {
3047+
// `indent` sets what the requirement is; `style` decides which lines are
3048+
// measured against it. A tight continuation is CommonMark lazy
3049+
// continuation, so `any` accepts it however the requirement was derived.
3050+
let any = rule_with(&[("indent", toml::Value::Integer(4))]);
3051+
let ctx = LintContext::new("- item\n wrap\n", MarkdownFlavor::Standard, None);
3052+
assert!(
3053+
any.check(&ctx).unwrap().is_empty(),
3054+
"style = any accepts tight lazy continuation"
3055+
);
3056+
3057+
let aligned = rule_with(&[
3058+
("indent", toml::Value::Integer(4)),
3059+
("style", toml::Value::String("aligned".to_string())),
3060+
]);
3061+
let warnings = aligned.check(&ctx).unwrap();
3062+
assert_eq!(warnings.len(), 1, "style = aligned raises it: {warnings:?}");
3063+
assert!(warnings[0].message.contains("expected 4"));
3064+
assert_eq!(aligned.fix(&ctx).unwrap(), "- item\n wrap\n");
3065+
}
3066+
29353067
#[test]
29363068
fn aligned_tight_underindented_fence_inside_item_left_alone() {
29373069
// A fenced block is a structural construct; aligned mode does not

0 commit comments

Comments
 (0)