Make a list of rules from the spec

[RichardLitt]

Initially, you can make them as packages in this folder, and then require them in index.js file as needed. When they are suitably abstracted, put them into their own packages.

[wooorm]

Here’s some more ideas. The checked ones are in GH-6 and GH-8.

List of rules

• file-stem
  • Allowing i18n support
  • Checking i18n tags (potential future extension)
• file-extname
• require-extname
• section-order
• no-unknown-sections
• require-sections

List of external rules that may be useful

• wooorm/remark-lint#remark-lint-no-missing-blank-lines — This checks for blanks between anything, not sections.
• davidtheclark/remark-lint-no-dead-urls
• qard/remark-lint-code (todo: create a remark-lint-code-standard plugin)
• remark-lint-appropriate-heading should allow for repository / folder / package name in italics.

List of random ideas for rules

• Rule to check that banner / badges don’t have headings
• Rule to check that banner links to a local image
• Rule to check that shields.io badges are used, if available, instead of alternatives
• Rule to check that badges are delimited by newlines
• Rule to check that short description is less than 120 characters.
• Rule to check that short description is delimited by blank lines
• Rule to check that short description matches package.json#description (e.g., using levenshtein-edit-distance to check for an 80% match?)
• Rule to check that short description matches GitHub description (if hosted on GH), see above
• Rule to check that ToC matches all further level-2 headings
• Rule to check that ToC does not include level-5 or level-6 headings
• Rule to check that install section has a code-block
• Rule to check that in install, the a paragraph before the code block mentions a package manager (e.g., npm)
• Rule to check that if there’s a contributing.md file, it’s linked in the Contribute section
• Rule to check that Contribute contains a link to issues

[wooorm]

Finally, as a start to validate the schema / heading outline, I created the following list from the spec:

Schema

• Title (required)
• Banner (optional, no title, paragraph with link and image nodes to local image)
• Badges (optional, no title, paragraph with newline delimited links with images)
• Short Description (required, no title, block quote)
• Long Description (required, no title, free form)
• Table of Contents (depends: required if more than 100 lines; list of links and optional nested lists)
• Security (optional)
• Background (optional)
• Install (depends: required if installable, code block and free form)
  • Dependencies (optional)
  • Updating (optional)
• Usage (depends: required if installable, code block and free form)
  • CLI (depends: required if usable on command line, code block and free form)
• ??? (Extra sections, no title, zero or more free-form sections with titles)
• API (optional, free form)
• Maintainer|Maintainers (optional, short list of links)
• Contribute (required, free-form)
• License (required, free-form)

[RichardLitt]

That looks right to me! Maintainer is optional, now. This should be relatively easy to check - for instance, the banner, badges, short and long description could be ignored in a heading check. Check the beginning to match, and the last two, and then note if any of the ones present are mistakenly put in the extra sections bit.

[wooorm]

Yeah I was thinking about how to check the heading-less stuff too. I came up with the idea of a utility that transforms the AST into a schema (an object form of the above), which you can then check for validity (or use for other tools!)

[RichardLitt]

The headingless-stuff should only really be in the main section before any second level headers (which would be TOC, background, security, or install). So, that should be in a separate check. That makes checking the titles easier, right?

[wooorm]

True, yeah definitely! I was thinking more about how to do it perfectly, how it’s supposed to be, than how to do it quickly/for now!

[wooorm]

Modified the above schema to make Maintainers optional.

[wooorm]

#4 (comment) updated for GH-8.