Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add markdownlint settings #10334

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

o-l-a-v
Copy link
Contributor

@o-l-a-v o-l-a-v commented Jan 6, 2025

Summary

In VSCode with Markdownlint (https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) and default rules enabled, it'd autocorrect a few things that do not seem to be what the project wants for its doc. For instance:

MD014 - Dollar signs used before commands without showing output

Would corrent

```console
$ winget install --id=astral-sh.uv  -e
```

to

```console
winget install --id=astral-sh.uv  -e
```

MD046 - Code block style

Says installation.md uses inconsistent code block style.

Seems the doc must use it for it to look good with mkdocs?

Test Plan

Affects developer experience.

@zanieb
Copy link
Member

zanieb commented Jan 6, 2025

I'm a little hesitant to add configuration for tools we're not using / enforcing. Does markdownlint catch anything we'd want to enforce?

@zanieb zanieb added the internal A refactor or improvement that is not user-facing label Jan 6, 2025
@o-l-a-v
Copy link
Contributor Author

o-l-a-v commented Jan 6, 2025

Very understandable. 😊

What IDE do contributors typically use, and do they lint markdown while editing in the IDE itself? How is that linting configured? I like immediate feedback vs. waiting for CI/CD tests. Markdownlint seems pretty universal for Markdown linting.

I linked a VSCode extension ( https://github.com/DavidAnson/markdownlint ), but it's heavily influenced by:

Other linting tools also uses markdownlint for markdown, like:

I think other tools would use .markdownlint.json too.


If you'd like a config to only apply in VSCode, Markdownlint (the extension) configuration can also be added to .vscode/settings.json. Example:

{
  "markdownlint.config": {
    "default": true,
    "MD013": {
      "line_length": 100
    },
    "MD014": false,
    "MD046": false
  }
}

If you have a different way to get feedback from a markdown linter while editing, I'll adapt.

If you don't want .markdownlint.json I'm fine with that too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
internal A refactor or improvement that is not user-facing
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants