Describe the Request
Most group repositories end up adhering to a set of repository rules for their linters, prettier, and so on. Since the majority of what we use are markdown files that are laced with other code, we'll need several of these files to capture all of the code that we will run across.
Do you intend to Submit a Pull Request to add this request (Yes/No)?
Yes
Additions Only
Use Case
What is your use case for asking this? Your perspective will be helpful in possible implementation of this.
-
Linters help generate uniformity, consistency, and reliability. The same .markdownlint.json
that ends up living in the root of the repository can be used to automate linting on all Pull Requests, and also be used by users who fork or clone the repository in their IDE's. With a little work, the rules can also be applied within Obsidian-Linter as they too have begun implementation of many of the rules of Markdown Linter.
-
We have users making videos, generating income, and putting their reputations out there for users. We want to make sure we take as much human error out of the equation.
-
If we use linters and prettier without determining what standard we need, we're gonna have a very bad time!
Examples
Here is the markdown lint recommendations for a file that Josh shared. This is using an entirely blank ignore of rules.
![Markdown Rules](https://user-images.githubusercontent.com/68425372/215880004-42f850b2-df96-4387-9194-41f3b7a0e41a.png)
So we see:
MD041/first-line-heading/first-line-h1: First line in a file should be a top-level heading
If we're using infoboxes, or if we have a title: in the YAML, we probably want to have this be ignored.
MD022/blanks-around-headings/blanks-around-headers: Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below]
In an infobox, thats gonna be a bad time, but outside of it, that would be real nice for readability. We could certainly create a rules exception that targets both.
MD024/no-duplicate-heading/no-duplicate-header: Multiple headings with the same content
Does =this.file.name
really need to be listed in multiple spots on a template? Can't one of those spots be a subtitle? Hmmm??? It would shame to get rid of this markdown rule, else you'd end up with.
Trailing spaces depends on the parser, and we have to decide if we want it.
MD013/line-length: Line length [Expected: 80; Actual: 1135]
Line length is all about readability and accessibility. In some cases, you have to wonder just how big a paragraph is too big. For the 1135 line length, it came from a statblock on Adult Crystal Dragon.
desc: "โญ ([[primal]], [[transmutation]]); __Frequency__ once per day __Trigger__ The crystal dragon damages a creature made of flesh with a jaws [[Strike]] __Effect__ The dragon embeds transformative crystals in the creature's flesh. The creature must attempt a DC 30 Fortitude save.\n__Critical Success__ The target is unaffected.\n__Success__ The target is [[slowed|slowed 1]] for 1 round as portions of its flesh turn crystalline.\n__Failure__ The target is [[slowed|slowed 1]] and must attempt a Fortitude save at the end of each of its turns; this ongoing save has the [[incapacitation]] trait. On a failed save, the [[slowed|slowed]] condition value increases by 1 (or by 2 on a critical failure). A successful save reduces the [[slowed|slowed]] condition value by 1. A creature unable to act due to the [[slowed|slowed]] condition from Crystallize Flesh is [[petrified|petrified]] permanently, transforming into a crystalline statue. The effect ends if the creature is [[petrified|petrified]] or the [[slowed|slowed]] condition is removed.\n__Critical Failure__ As failure, but the target is initially [[slowed|slowed 2]]."
We'll probably have to at least increase the line length to 4-500, and ignore certain folders.
MD047 - Files should end with a single newline character
I am just going to leave this here.
See all the rules here: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
Let's Discuss.
I'd like to have this done by 2023-02-15, so I can get this loaded as a GitHub action, get it in the root of the repo, get a guide out, and we can then move onto YAML or CSS Linting.
I'll get a base markdownlint.json up in the PR for us to work on with the hour.