Goals

[vweevers]

• Standardize README.md and CHANGELOG.md files.
• Main entrypoint (hallmark) is a single module cli like standard. This will fix and lint at the same time.
• Should accept multiple files (hallmark *.md).
• Follow same ignore logic as standard
• Nice to have: usable on complete and partial files. If you run it on an empty readme, it should generate all standard sections, taking information from package.json, GitHub, etc.
• Remark plugins will be bundled in remark-hallmark-preset
• A standard outline is more important than style.
• Favor consistency within document over an enforced style. hard to do with --fix
• Take rules from RichardLitt/standard-readme and the older zcei/standard-readme and perhaps Repository creation and readme conformity guidelines ipfs/community#45, but leave more room for personal preference.
• No configuration (except for community metadata)
• Some sections will be optional (TOC, Contributors). If the header exists, update the section.
• While developing this, run it on a few README's (Level, personal, ..) to ensure we don't get too aggressive.
• Report on dead internal links (remark-validate-links)
• Report/error on dead external links (remark-lint-no-dead-urls)

[ralphtheninja]

It should report/error on dead links, either urls or internal links (links to sections that doesn't exist)

[vweevers]

For that we can use one of:

• remark-lint-no-dead-urls
• remark-validate-links

[vweevers]

To enforce consistency we can consider:

• remark-preset-lint-consistent

[vweevers]

If standard is installed, run standard-markdown, but refactored as a remark plugin. Maybe we can use remark-lint-code.

[ralphtheninja]

Do we need to implement/publish any remark plugins ourselves?

[vweevers]

Yes, but we can start with existing plugins. Later on, I'd like to have plugins for specific readme sections, such as:

• "Install(ation)": if it doesn't exist, add it, with basic npm install instructions
• "License|Licence": insert based on package.json license
• Description (with character limit, and warn if it doesn't match package.json description)
• Warn if badge style is not consistent (?style=flat-square etc)
• Enforce SVG badges
• Perhaps a simple plugin to merely enforce existence of sections (like "Example")
• Wrapper for remark-toc to bundle it with remark-collapse

And we can perhaps reuse remark-module-bookmarks from Awesome. Get package names from dependencies, linkify those automatically. Perhaps only linkify the first occurrence of module.

[ralphtheninja]

What does linkify mean?

[vweevers]

Replacing a text like abstract-leveldown with a link to its github repo (or npm package might be better).

[vweevers]

It should replace License & Copyright with License.