Request: Mandatory headings about markdownlint

[DavidAnson]

Seems reasonable, I like the design you've proposed. I'll look into this soon when I work through the backlog of markdownlint issues. Thanks!

[DavidAnson]

I went back and forth on this implementation a bunch. :| What ended up seeming like a reasonable first attempt is what you see in the associated commit. I think that it addresses the common scenarios clearly and in a way a beginner could use (using your syntax, with some changes). I will add more detailed custom error information as part of #23. I may still add RegExp support. If you feel this is not sufficient to start with, please let me know!

[originalfoo]

Example rule config:

{ headings: [ '# Introduction', '## About', '## Dependencies' ...], ordered: true }

The # at start of strings denotes heading level - if present, the rule also validates that the heading, if found, is using the specified heading level.

[originalfoo]

Here's a rough code draft if it's any use:

  {
    "name": "MD042",
    "desc": "Mandatory headers are missing or wrong level/sequence",
    "tags": [ "headers" ],
    "aliases": [ "mandatory-headings" ],
    "func": function MD042(params, errors) {
      /**
       * Example options:
       *
       * { headings: [ '# Overview', '## About', '## Notes' ], ordered: true }
       *
       * Notes:
       *  * No `#` for heading means "any level"
       *  * Rule ignores any headings not listed in array
       */
      if ( !params.options
        || !params.options.headings
        || !params.options.headings instanceof Array ) {
        return;
      }
      var headings = params.options.headings,
          ordered  = params.options.ordered || true;
      // Split headings array in to texts and levels arrays:
      var texts  = []; // heaidng text
      var levels = []; // heading level (0 if not specified)
      headings.forEach(function(heading, idx) {
        var hed = heading.split('#');
        texts[idx]  = hed.pop().trim(); // heading text
        levels[idx] = hed.length; // heading level
      });
      // Verify headings in target document:
      // If heading is found, it gets removed from texts/levels
      // array regardless of whether it has error
      forEachHeading(params, function forHeading(heading, content) {
        // heading = "heading_open" token
        var level = parseInt(heading.tag.slice(1), 10);
        // content = heading text
        var text  = content.trim();
        if (ordered) {
          if (texts[0] === text) { // found in right place
            if (levels[0] && levels[0] !== level)
              errors.push(heading.lineNumber);
            // remove form lists
            texts.shift();
            levels.shift();
          } else { // maybe it's out of sequence?
            var wrongPos = texts.indexOf(text);
            if (wrongPos > -1) { // found, but out of sequence
              errors.push(heading.lineNumber);
              // remove from lists
              texts.splice(wrongPos,1);
              levels.splice(wrongPos,1);
            }
          } // else ignore non-listed headings
        } else { // unordered
          var pos = texts.indexOf(text);
          if (pos > -1) { // found, order not important
            if (levels[pos] && levels[pos] !== level)
              errors.push(heading.lineNumber);
            // remove from lists
            texts.splice(pos,1);
            levels.splice(pos,1);
          } // else ignore non-listed headings
        }
      });
      // any missed headings?
      if (texts.length) errors.push(0);
    }
  },

[DavidAnson]

Nice, thanks! I will think about the algorithm independently as well. Also, what about another option only=true to fail the check if some other header is present?

[originalfoo]

Yes, good idea!

[DavidAnson]

Thinking about this in the context of something like Wikipedia, I'm not sure what we have so far is expressive enough. So I am playing with the idea of casting this as a regular expression scenario. Imagine if the list of headers was presented as a string similar to how you propose and then the rule runs a regular expression against it.

Example: # Intro\n# Body\n# Summary\n

This makes it possible to enforce simple rules like "exactly these three headers in this order", more complicated ones like "this set of 10 headers, 5 of which are optional", more generic ones like "only level one and two headings", or even stuff like "API documentation where each method is a level two heading followed by any number of level three headings for each parameter".

The concern I have with this is that violations will be harder to identify because there won't be meaningful line numbers. However, in order to cover the kinds of scenarios I see this being used for (GitHub Readme, OSS documentation), I'm thinking such a level of expressivity is necessary - and would be difficult to implement manually.

[originalfoo]

I agree the regex approach would be a big improvement in terms of flexibility, so long as your docs provide decent examples for scenarios you cited - regex are often difficult to comprehend for people involved in maintaining documentation and style guides, etc.

Maybe a helper function could be provided that would take a nested JS object of specific format and make a regex from it?

Regarding the inability to report violation line numbers, I think that is an acceptable tradeoff in the specific case of headings - because headings are simple to spot in documents. Alternatively, is there some way to pick apart the regex and at least state which headings are missing or incorrect (even if we can't determine line number)?

At the very least, we would need the ability to define a custom error message to point people at style guide in case of violations.

[sagiegurari]

this is a really good feature.
when will this be published to npm?

[DavidAnson]

I published version 0.2.0 a few minutes ago. :)

[sagiegurari]

thanks

[originalfoo]

Been away due to RL issues, but great to see this feature implemented - many thanks!