An automatic awesome list generator


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
10Jul 31, 2018Jul 29, 2018Minified + gzip package size for auto-awesome-list in KB




An automatic awesome list generator

What is an awesome list?

See sindresorhus' awesome manifesto for what an awesome list is. They are basically curated lists of resources for developers.

What does auto-awesome do?

Auto-awesome takes a barebones markdown file and does the heavy lifting for turning it into an awesome list! It adds 2 new things to the markdown syntax, a table of contents tag, and a listing tag, which searches on GitHub for that piece of software and adds a description and link for it.


If you want to see an example of this, look at, and


This can take quite some time for a large file, as it has to look up each item on the list.

If you are getting an API rate limit error, your file is too big and/or you are re-running this fast. To authenticate to get a higher rate limit, generate a github token (with minumum permissions), and set the github_token env variable to the token.


This extends markdown with 2 more tags.

  • !toc! inserts a table of contents for all headings under it. (you can only have one of these)
  • !!repo searches GitHub for repo and inserts a link and description of it.
  • !!user/repo gets the link and description for the repo at user/repo on GitHub and inserts it.
  • !!repo~name gets the repo (in the format seen above), and sets the name to name. (by default it takes the repository name from GitHub, which sometimes fails in examples such as npm/cli)


Requiring auto-awesome-list after installing it with npm install auto-awesome-list returns a very simple function.


The first parameter of the function is a string containing the raw, input markdown. You can get this using fs, or other means. The second parameter is a callback, that takes one parameter, the processed markdown file.


const autoAwesome = require("auto-awesome-list");
const md = "!!nodejs"
autoAwesome(md, data => {
    console.log(data); // logs: [node]( - Node.js JavaScript runtime...


Install with npm install -g auto-awesome-list


Reads input from stdin or the file in the passed parameter. Outputs to stdout or the file listed in the '-o' argument.


auto-awesome -o

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from