New rule: Report what looks like a title but isn't

[jfmengels]

What the rule should do:

Report when (module/function/type) documentation contains what looks like a title but isn't.

What problems does it solve:

Fixes a Markdown issue that can surprise documentation authors.

Example of things the rule would report:

module A exposing (..)
{-|

#Title

-}

a = 1

Here's an example of the result: https://package.elm-lang.org/packages/stil4m/elm-syntax/7.2.6/Elm-Syntax-Infix (#Types)

Multiplying the number of #'s

Example of things the rule would not report:

module A exposing (..)
{-|

# Title

-}

a = 1

When (not) to enable this rule:

This can probably have some false positives, if authors genuinely want to start a line with #.

I am looking for:

• General feedback
• Information as to whether there is a maximum number of # for titles.
• Information as to whether this will be a problem in practice
• Information: Is this issue only a problem with the current Markdown implementation of the packages website, or is this part of the GitHub Flavored Markdown spec as well?

(cc @dillonkearns who might know some of the answers)

[lue-bird]

• Max number of # is 6:
• This issue is part of the GitHub Flavored Markdown spec as well:
• Yes, I think that rule will be helpful because
  • #Title is pretty much always meant as # Title
  • It is quite a common mistake I see (because you either expect it to work or you just forgot to add the space)
  • it is easy to find and to provide an automatic fix for

[dillonkearns]

You might find markdownlint to be a useful reference here as well. I actually use markdownlint in VS Code and find it helpful for things like making sure heading levels don't skip a level.

https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md