[GH-ISSUE #569] Tools for enforcing awesome-style? #2666

New Issue

GiteaMirror · 2026-04-15T10:42:56-05:00

GiteaMirror commented

2026-04-15 10:42:56 -05:00

Originally created by @paulirish on GitHub (Mar 10, 2016).
Original GitHub issue: https://github.com/sindresorhus/awesome/issues/569

In the manifesto there are a few suggestions and requirements. For example..

style

grammatically correct
no typos
no markdown errors
consistent style (e.g. "link - Description with a period.")

build

table-of-contents generated

Have any list maintainers written some scripts to either lint for style issues? Also interested in boring build scripts to automate TOC generation with DocToc, etc.

Originally created by @paulirish on GitHub (Mar 10, 2016). Original GitHub issue: https://github.com/sindresorhus/awesome/issues/569 In the [manifesto](https://github.com/sindresorhus/awesome/blob/master/awesome.md) there are a few suggestions and requirements. For example.. ##### style - grammatically correct - no typos - no markdown errors - consistent style (e.g. "[link](/thing) - Description with a period.") ##### build - table-of-contents generated --- Have any list maintainers written some scripts to either lint for style issues? Also interested in boring build scripts to automate TOC generation with DocToc, etc.

GiteaMirror closed this issue

2026-04-15 10:42:56 -05:00

GiteaMirror commented

2026-04-15 10:42:56 -05:00

@sindresorhus commented on GitHub (Mar 11, 2016):

👍 Would be nice to just be able to tell people to add a Travis check. Very few follow the guidelines and I do a lot of manual job commenting on that.

The only prior art I know of is an awesome bot (see https://github.com/sindresorhus/awesome/pull/478), but it only checks for outdated links, so not very useful.

@sindresorhus commented on GitHub (Mar 11, 2016): :+1: Would be nice to just be able to tell people to add a Travis check. Very few follow the guidelines and I do a lot of manual job commenting on that. ## The only prior art I know of is an awesome bot (see https://github.com/sindresorhus/awesome/pull/478), but it only checks for outdated links, so not very useful.

GiteaMirror commented

2026-04-15 10:42:57 -05:00

@sindresorhus commented on GitHub (Mar 11, 2016):

@wooorm Does something like this exist in the retext/remark ecosystem?

@sindresorhus commented on GitHub (Mar 11, 2016): @wooorm Does something like this exist in the retext/remark ecosystem?

GiteaMirror commented

2026-04-15 10:42:57 -05:00

@wooorm commented on GitHub (Mar 11, 2016):

Hi Sindre, Paul, great idea!

no markdown errors, consistent style

I believe remark, the markdown processor, could help here. Probably though its lint plugin, which checks patterns in markdown and triggers warnings. It checks for several possible style violations (e.g., emphasis markers, * or _), which each can be configured, turned on, or turned off. And, it supports external rules, for example: vhf/remark-lint-alphabetize-lists, which ensures lists are sorted properly.

Which brings me to a similar project, vhf/free-programming-books-lint, which implemented the aforementioned rule. This project wraps remark and remark-lint and enforces the free-programming-book style in their .travis.yml file.

P.S. also interesting: remark-validate-links

table-of-contents

Maybe remark-toc, or of course one of the non-remark plugins if you want more control.

grammatically correct, no typos

Nothing good so far. I investigated this but there’s no good solution to implement this in a Travis task, yet. I’m half-way with n-spell, plain-JavaScript (Hunspell) spelling, which will make this possible. But I got bored...

Hope this helps!

@wooorm commented on GitHub (Mar 11, 2016): Hi Sindre, Paul, great idea! #### no markdown errors, consistent style I believe [remark](https://github.com/wooorm/remark), the markdown processor, could help here. Probably though its [lint](https://github.com/wooorm/remark-lint) plugin, which checks patterns in markdown and triggers warnings. It checks for several possible style violations (e.g., emphasis markers, `*` or `_`), which each can be configured, turned on, or turned off. And, it supports external rules, for example: [`vhf/remark-lint-alphabetize-lists`](https://github.com/vhf/remark-lint-alphabetize-lists), which ensures lists are sorted properly. Which brings me to a similar project, [`vhf/free-programming-books-lint`](https://github.com/vhf/free-programming-books-lint), which implemented the aforementioned rule. This project wraps remark and remark-lint and enforces the free-programming-book style in their [`.travis.yml`](https://github.com/vhf/free-programming-books/blob/83ad2ccb681432e79c808cfa5bb418ec84a8369b/.travis.yml#L5-L7) file. P.S. also interesting: [`remark-validate-links`](https://github.com/wooorm/remark-validate-links) #### table-of-contents Maybe [`remark-toc`](https://github.com/wooorm/remark-toc), or of course one of the non-remark plugins if you want more control. #### grammatically correct, no typos Nothing good so far. I investigated this but there’s no good solution to implement this in a Travis task, yet. I’m half-way with n-spell, plain-JavaScript (Hunspell) spelling, which will make this possible. But I got bored... --- Hope this helps!

GiteaMirror commented

2026-04-15 10:42:57 -05:00

@sobolevn commented on GitHub (Jun 21, 2016):

When creating awesome-cryptography, I was in doubt with how to enforce the style-consistency. Thanks for @wooorm for his awesome remark-lint.

My solutions was:

Validating Markdown style with remark-lint
Validating that list-items are ordered alphabetically: remark-lint-alphabetize-lists
Validating links to be unique and alive: remark-lint-are-links-valid
Checking that list items are ending with period: remark-lint-list-item-punctuation

Here's the setup: package.json

@sobolevn commented on GitHub (Jun 21, 2016): When creating [`awesome-cryptography`](https://github.com/sobolevn/awesome-cryptography), I was in doubt with how to enforce the style-consistency. Thanks for @wooorm for his awesome `remark-lint`. My solutions was: 1. Validating Markdown style with `remark-lint` 2. Validating that list-items are ordered alphabetically: [`remark-lint-alphabetize-lists`](https://github.com/vhf/remark-lint-alphabetize-lists) 3. Validating links to be unique and alive: [`remark-lint-are-links-valid`](https://github.com/wemake-services/remark-lint-are-links-valid) 4. Checking that list items are ending with period: [`remark-lint-list-item-punctuation`](https://github.com/wemake-services/remark-lint-list-item-punctuation) Here's the setup: [`package.json`](https://github.com/sobolevn/awesome-cryptography/blob/master/package.json)

GiteaMirror commented

2026-04-15 10:42:58 -05:00

@sindresorhus commented on GitHub (Aug 1, 2016):

I've started work on an official Awesome linter. ✨

I could use some feedback and help → https://github.com/sindresorhus/awesome-lint/issues/3

@sindresorhus commented on GitHub (Aug 1, 2016): I've started work on an official Awesome linter. ✨ I could use some feedback and help → https://github.com/sindresorhus/awesome-lint/issues/3