Rules for documentation files (.md)

With hundreds of repos across dozens of developers in our organization, ensuring proper documentation within the repo can be a challenge. Is it possible to set up rules against .md files? For example

A missing or empty readme.md file should be a critical issue.
A readme.md without links to the:

  • pipeline
  • deployments
  • sonarqube
  • CMDB
  • support call instructions
  • log locations
  • etc…
    would be each be a major.

Obviously each organization is going to have different requirements and patterns in this space, so even just a configurable filename + regex recognition would be good enough to get rolling. If this is something that’s already out there and I’m just missing it, I’d appreciate a pointer!

Hi, @ThatRickGuy, I like your idea, although I think finding a commonly accepted set of rules for Markdown files might also be difficult.

Some rules that could perhaps be useful:

Section headers should be unique

This could be a minor code smell. (?) Maybe restrict this rule to top-level headers?

Noncompliant example:

# Foo Section

lorem ipsum ...

# Bar Section

some more text ...

# Foo Section

^ noncompliant because same header again

Fenced code block should specify the language (for syntax highlighting)

Noncompliant example

Some sample Java code:

```
System.out.println("hello world");
```

Compliant example

Some sample Java code:

```java
System.out.println("hello world");
```

Lines should be hard-wrapped after 80 characters.

Noncompliant example

Very long text bla bla alskdjfh lkasdjh ask walks dfaslkjfsajlfajslfsd jlhasj fafhksa fksa too long.

Compliant example

Very long text bla bla alskdjfh lkasdjh ask walks  
dfaslkjfsajlfajslfsd jlhasj fafhksa fksa too long.

See also

These style guides: