feat(lint-configs): Add markdownlint config.#45
Conversation
WalkthroughA new configuration file named Changes
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds a custom markdownlint configuration file to enforce non-default formatting rules for markdown documents.
- Introduces several rule customizations (e.g., MD003 using ATX style, MD009 with strict list item rules, MD013 with a custom line length setting).
- Disables or adjusts certain rules to accommodate specific documentation practices, such as allowing HTML tags in MD033.
| spaces_per_tab: 4 | ||
| MD013: | ||
| line_length: 100 | ||
| stern: true |
There was a problem hiding this comment.
It appears that 'stern' might be a typo; consider using 'strict' for consistency with MD009 if that was intended.
| stern: true | |
| strict: true |
There was a problem hiding this comment.
MD0013 has a stern option.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
lint-configs/.markdownlint-cli2.yaml(1 hunks)
🔇 Additional comments (13)
lint-configs/.markdownlint-cli2.yaml (13)
2-4: MD003 heading style set to ATX
Thestyle: "atx"option enforces consistent ATX‐style headings, aligning with project conventions.
4-6: Unordered list marker configured as asterisk
Specifyingasteriskfor MD004 ensures uniform list markers across all markdown files.
6-8: Enforce empty lines around list items (MD009)
Enablinglist_item_empty_lines: truewithstrict: truerequires blank lines around list items, improving readability in nested lists.
9-11: Allow trailing spaces in code blocks and standardize tab width (MD010)
Settingcode_blocks: falsepermits trailing spaces in fenced code blocks, andspaces_per_tab: 4ensures consistent indentation.
16-17: Limit duplicate heading checks to sibling sections (MD024)
MD024.siblings_only: truecorrectly restricts duplicate heading warnings to sibling levels, preventing false positives across different sections.
19-20: Allow inline HTML (MD033 disabled)
Disabling MD033 permits necessary HTML tags (e.g., Mermaid diagrams) without lint errors.
21-22: Set thematic break style to---(MD035)
Using---standardizes horizontal rules across markdown content.
23-24: Enforce fenced code block style (MD046)
style: "fenced"ensures all code blocks use consistent delimiter syntax.
25-26: Use backticks for inline code spans (MD048)
Choosingbacktickpromotes uniform inline code formatting throughout documentation.
27-29: Emphasis marker set to asterisk (MD049)
style: "asterisk"avoids ambiguity when underscore characters appear in emphasized text.
31-33: Disable built-in link validation for MyST-Parser (MD051)
Turning off MD051 supports MyST-Parser’s extended link syntax and defers validation to Sphinx.
34-35: Enable shortcut link syntax (MD052)
Settingshortcut_syntax: trueallows[text]–style links, improving brevity and readability.
36-38: Require leading and trailing spaces in inline code (MD055)
style: "leading_and_trailing"enforces clear delimitation around inline code spans for better readability.
| MD013: | ||
| line_length: 100 | ||
| stern: true | ||
| tables: false |
There was a problem hiding this comment.
Typo in MD013 configuration key: use strict instead of stern
The field stern: true appears to be a typo. The correct option to enforce strict line‐length is strict. For example:
MD013:
line_length: 100
- stern: true
+ strict: true
tables: false📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| MD013: | |
| line_length: 100 | |
| stern: true | |
| tables: false | |
| MD013: | |
| line_length: 100 | |
| strict: true | |
| tables: false |
There was a problem hiding this comment.
It's not a typo. MD0013 has a stern option.
There was a problem hiding this comment.
🧩 Analysis chain
According to the results from my web search:
- DavidAnson/markdownlint has a "line_length" rule (MD013) which has a "strict" option but no "stern" option is documented [1].
- The official documentation for markdownlint explicitly mentions "strict" as an option for MD013 [2].
- The options available for MD013 are: line_length, heading_line_length, code_block_line_length, code_blocks, tables, headings, headers, and strict [3].
@kirkrodrigues I double-checked the markdownlint documentation, and it appears that MD013 has a "strict" option but not a "stern" option. The official documentation only mentions "strict" as a valid configuration parameter. Could you please double-check or share your reference if you have different information?
Citations:
[1] https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
[2] https://github.com/DavidAnson/markdownlint/blob/v0.25.1/doc/Rules.md#md013---line-length
[3] https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
🌐 Web query:
markdownlint MD013 rule options "stern" vs "strict"
💡 Result:
The MD013 rule in markdownlint is used to enforce line length in Markdown documents. The rule has two notable modes for handling long lines: strict and stern.
Strict Mode
- Default Setting:
false - Function: In strict mode, if the
strictparameter is set totrue, the rule will report any line that exceeds the configured line length as a violation. This means all long lines, including those without any whitespace beyond the maximum length (like long URLs), will be flagged as errors.
Stern Mode
- Default Setting:
false - Function: If the
sternparameter is set totrue, the rule will warn about lines that are too long and could be fixed (i.e., lines with whitespace beyond the configured length) but will allow lines without spaces (such as long URLs) even if they are longer.
Comparison of Modes
- Strict Mode is more severe, treating all long lines as errors.
- Stern Mode is less severe, warning about long lines with whitespace but allowing lines without spaces (e.g., URLs).
Both modes can be used to enforce different levels of line length control depending on the context. You can exclude specific elements like code blocks, tables, or headings from these rules by setting their respective parameters to false in your markdownlint configuration[1][2][3].
Citations:
- 1: https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
- 2: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
- 3: http://xiangxing98.github.io/Markdownlint_Rules.html
- 4: https://jackdewinter.github.io/2021/09/20/markdown-linter-race-to-the-finish/
- 5: https://juejin.cn/post/7075518787105062919
- 6: https://docs.superoffice.com/contribute/markdown-guide/markdownlint.html
- 7: https://www.jianshu.com/p/d05586431a0b
- 8: https://www.npmjs.com/package/markdownlint
- 9: https://git.hackliberty.org/Git-Mirrors/thgtoa/compare/ec6ff4f3e4c02d68814d86ece6a9c09fb8d73873...dadade4cc129f71f4e71cbd06b1f9ed118c4fbac?style=split&whitespace=show-all&show-outdated=
- 10: https://dev.to/jonasbn/blog-post-markdownlint-24ig
@kirkrodrigues You're absolutely right, and I apologize for my mistake! The MD013 rule does indeed have a stern option, which is different from strict:
stern: true: Warns about long lines with whitespace (that could be fixed) but allows long lines without spaces (like URLs)strict: true: Reports all lines exceeding the length limit, regardless of content type
Your configuration using stern: true is perfectly valid and actually provides a more practical approach by allowing long URLs while still enforcing line length where possible. Thank you for the correction!
🐰✨ (learning something new)
✏️ Learnings added
Learnt from: kirkrodrigues
PR: y-scope/yscope-dev-utils#45
File: lint-configs/.markdownlint-cli2.yaml:12-15
Timestamp: 2025-05-03T17:46:34.652Z
Learning: In markdownlint, the MD013 (line length) rule has two different enforcement options: "stern" and "strict". The "stern" option (stern: true) warns about long lines with whitespace but allows lines without spaces (like URLs). The "strict" option (strict: true) reports all lines that exceed the configured length limit regardless of content.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
LinZhihao-723
left a comment
There was a problem hiding this comment.
Reviewed all the config options included in this PR. They all make sense to me.
It seems like not all the rules are configured in this set. I don't get enough time to go through all the unspecified rules for now, and I assume the current rule set is sufficient. If needed, I think we can configure other rules in future PRs.
Description
As the title says. The config only sets rules which require different values than their defaults. The rules are documented here.
Checklist
breaking change.
Validation performed
Validated with the docs in clp as follows:
Summary by CodeRabbit