fix(markdown-validator): use global markdownlint config with MD013=160

[JacobPEvans]

Summary

Updates markdown-validator plugin to use a global markdownlint configuration with 160-character line length.

• Adds --config ~/.markdownlint-cli2.yaml flag to validation command
• Documents global config requirement in README
• Updates repository .markdownlint.json with correct settings

Changes

• validate-markdown.sh: Add --config flag to markdownlint-cli2 command
• README.md: Document global config requirement and recommended settings
• .markdownlint.json: Update with MD013 (160/120/160) and disable MD060

Configuration

config:
  default: true
  MD013:
    line_length: 160
    heading_line_length: 120
    code_block_line_length: 160
    tables: false
  MD060: false
fix: true

Test Plan

• Install updated plugin
• Create ~/.markdownlint-cli2.yaml with recommended config
• Test validation with 160-character markdown lines
• Verify validation passes for lines up to 160 chars

Related

• Companion PR in nix-config repo: fix: configure markdownlint MD013 line length to 160 characters nix#517
• Resolves issue where default 80-char limit breaks sentences mid-sentence

🤖 Generated with Claude Code

---

Important

Updates markdown-validator to use global markdownlint config with specific line length settings and documents the requirement.

• Behavior:
  • Adds --config ~/.markdownlint-cli2.yaml flag to validate-markdown.sh for markdownlint-cli2.
  • Requires global markdownlint config file, documented in README.md.
• Configuration:
  • Updates .markdownlint.json with MD013 settings: line_length: 160, heading_line_length: 120, code_block_line_length: 160, tables: false.
  • Disables MD060 in .markdownlint.json.
• Documentation:
  • Adds global config requirement and settings to README.md.

^{This description was created by for f334b6d. You can customize this summary. It will automatically update as commits are pushed.}

[gemini-code-assist]

Summary of Changes

Hello @JacobPEvans, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refines the markdown validation process by implementing a standardized global markdownlint-cli2 configuration. This change addresses previous limitations with default line length rules, promoting better readability and consistency in markdown files by allowing more flexible line lengths and disabling specific rules that caused conflicts, ultimately improving the developer experience when writing documentation.

Highlights

• Standardized Markdownlint Configuration: The markdown-validator plugin now utilizes a global markdownlint-cli2 configuration file located at ~/.markdownlint-cli2.yaml for consistent validation across projects.
• Increased Line Length Limits: The MD013 rule has been updated to allow longer lines: 160 characters for regular text, 120 for headings, and 160 for code blocks, while disabling line length checks for tables to prevent breaking sentences mid-sentence.
• Documentation Update: The README.md file has been enhanced with a new section detailing the requirement for the global markdownlint configuration, including recommended settings and explanations for key rules.
• Script Modification: The validate-markdown.sh script has been modified to explicitly pass the global configuration file to the markdownlint-cli2 command using the --config flag.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request updates the markdown-validator plugin to use a global markdownlint configuration, which is a good step towards consistent linting. The changes in the shell script, README, and local markdownlint config are clear and address the goal of increasing the line length limit. I've provided one suggestion to improve the robustness of the shell script by making the home directory path more portable and adding a check for the new required configuration file to provide better error messages to the user.

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 8cd7032 in 1 minute and 36 seconds. Click for details.

• Reviewed 81 lines of code in 3 files
• Skipped 0 files when reviewing.
• Skipped posting 3 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. .markdownlint.json:1

• Draft comment:
  The MD013 config now includes additional properties. Verify these settings align with your intended markdownlint behavior.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 15% None

2. markdown-validator/README.md:43

• Draft comment:
  Documentation for the global config is clear. Consider adding a link to markdownlint-cli2’s docs for further reference.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 15% This comment is purely informative, suggesting to add a link for further reference. It doesn't provide a specific code suggestion or highlight a potential issue with the code. According to the rules, purely informative comments should be removed.

3. markdown-validator/scripts/validate-markdown.sh:36

• Draft comment:
  Consider using the $HOME variable (or assigning the config path to a variable) instead of '~' for better portability and clarity.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% The comment is about a change that was made (adding the config flag). It's suggesting a code quality improvement - using $HOME instead of ~. However, I need to consider: 1) Is this actually a portability issue? In bash, ~ is widely supported and commonly used. 2) Is this suggestion actionable and clear? Yes, it provides a concrete alternative. 3) Is this important enough to warrant a comment? This seems like a minor stylistic preference rather than a real issue. The use of ~ in bash scripts is standard and well-supported. The claim about "better portability" is questionable - ~ works in all POSIX shells and is actually more concise. The suggestion doesn't seem to address a real problem. While $HOME might be slightly more explicit, ~ is perfectly valid and widely used in bash scripts. This might be an overly pedantic suggestion that doesn't address a real portability or functionality issue. The comment might be based on a misconception about shell portability. The use of ~ is standard in bash and shell scripts, and there's no strong evidence that this change would improve portability or clarity in a meaningful way. This appears to be a minor stylistic preference rather than a necessary code quality improvement. The rules state not to make comments that are "obvious or unimportant" - this falls into that category. This comment should be deleted. It's a minor stylistic suggestion without strong justification. The use of ~ is standard and acceptable in bash scripts, and the suggested change doesn't address a real problem or significantly improve code quality.

Workflow ID: wflow_JE5Lt0KmeVLIqioh

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[Copilot]

Pull request overview

This PR updates the markdown-validator plugin to use a global markdownlint configuration file with a 160-character line length limit, addressing issues where the default 80-character limit breaks sentences mid-sentence.

Changes:

• Adds --config ~/.markdownlint-cli2.yaml flag to markdownlint-cli2 command
• Documents the global configuration requirement and recommended settings in the README
• Updates the repository's .markdownlint.json with comprehensive MD013 settings and disables MD060

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
markdown-validator/scripts/validate-markdown.sh	Adds --config flag to specify global markdownlint configuration file path
markdown-validator/README.md	Adds new "Global Markdownlint Configuration" section with recommended YAML config and explanation of key settings
.markdownlint.json	Expands MD013 configuration with heading and code block line lengths, table settings, and disables MD060 rule

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JacobPEvans]

Response to review feedback on config file handling:

Fixed in commit f334b6d.

Changes made to validate-markdown.sh:

• Changed ~ to /Users/jevans for better portability across environments
• Added config file existence check before running markdownlint-cli2
• Provides clear error message directing users to the README if config is missing

This ensures the validation fails gracefully with helpful guidance rather than silently using default settings or producing confusing errors.

Addresses threads on lines 36-39 from both reviewers.

[JacobPEvans]

Response to review feedback on config format documentation:

Fixed in commit f334b6d.

Added a note in the README clarifying the structural differences between YAML and JSON config formats:

• YAML format (for ~/.markdownlint-cli2.yaml) uses a config: wrapper for rules and top-level fix: option
• JSON format (for .markdownlint.json) uses a flat structure without the config wrapper and omits the fix property

The note references this repository's .markdownlint.json as an example of the correct JSON structure. This should prevent confusion when users see both formats in the codebase.

Addresses thread on README.md lines 50-60.

[JacobPEvans]

Response to review feedback on config requirement language:

Fixed in commit f334b6d.

Updated the documentation language from "requires" to "uses" and added explicit documentation of the failure behavior:

• Changed: "This plugin uses a global markdownlint configuration file..."
• Added: "If this file is missing, the validation hook will fail with a clear error message prompting you to create it."

Combined with the script changes (config existence check with helpful error), this now accurately reflects the behavior: the config is enforced (not optional), but users get clear guidance when it's missing rather than confusing failures.

Addresses thread on README.md lines 45-46.

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed f334b6d in 1 minute and 50 seconds. Click for details.

• Reviewed 44 lines of code in 2 files
• Skipped 0 files when reviewing.
• Skipped posting 2 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. markdown-validator/README.md:45

• Draft comment:
  Good update clarifying the global config file requirement. The added note on YAML vs JSON formats is helpful, but ensure these guidelines stay in sync with the .markdownlint.json file.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 15% None

2. markdown-validator/scripts/validate-markdown.sh:36

• Draft comment:
  The new check for the global config file using "$HOME/.markdownlint-cli2.yaml" is a useful improvement. Consider making the config file path configurable via an environment variable for greater flexibility in different environments.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% The comment is suggesting an enhancement to make the config file path configurable. This is a "nice to have" feature suggestion rather than identifying a problem with the current implementation. The current code hardcodes the path to "$HOME/.markdownlint-cli2.yaml" and now validates its existence. The suggestion would add flexibility, but there's no evidence that this flexibility is needed. The rules state that comments should identify clear code changes that are required, not suggest optional enhancements unless they are clearly important. This seems like a speculative improvement rather than addressing a concrete issue. This could be a legitimate code quality improvement that makes the script more flexible and testable. The suggestion is actionable and clear, which the rules say is good for code quality refactors. While the suggestion is actionable, there's no evidence that this flexibility is actually needed or that the current hardcoded path is causing problems. The change in the diff was specifically to add validation for the config file, not to make it configurable. This is more of a "could be better" suggestion rather than identifying something that should be changed. This comment should be deleted. It's suggesting an optional enhancement rather than identifying a clear issue with the code. The rules emphasize not making comments unless there is clearly a code change required, and this is a speculative improvement without strong evidence it's needed.

Workflow ID: wflow_drqcbHrI2CFfvmUi

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}