README.md

Awesome List Compiler

This folder contains the tooling to auto generate a list of resources for an awesome style list.

It is designed to take the data from a series of YML files in a data directory and use handlebars to compile that in to the finished Readme.

Getting Start

• clone this repo git clone git@github.com:dotmh/awesome-dotmh.git
• change into the local repo cd ./awesome-dotmh
• change to using the specified version of node with nvm nvm use
• install dependencies for the build script with pnpm install
• generate the readme.md with pnpm build

Adding, Editing or Removing links

All the links are stored in yaml in the /data folder. Each Yaml file represents a Category on the main Readme.md. If they are organised into a folder then that folder is considered a group.

Adding, Editing or Removing a Link

Find the category that the link is in and then edit is corresponding yaml file. Under that file you will find an yaml array containing information on each link.

Example

name: My Stack
emoji: man_technologist
description: |
  This is the default stack that I use for most projects. I find it very productive and easy to work with.
  This isn't the only stack that I use, but it's the one that I use most often.
resources:
  - name: Typescript
    description: My favourite programming language
    link: https://www.typescriptlang.org/

You can edit the link by updating the information, to delete the link simple remove everything just before the - of the resource information to just before the next -

You can add a new link by adding a new element to represent that resources i.e.

- name: Name of the link (keep this one short)
  description: Description of the linked resource
  link: A link to the resource

Adding a new Category

Create a new file in the /data directory to represent the category you want to add links for. The file should be named the same as the name but using - instead of spaces. A number at the beginning controls the order categories appear on the README.

Example

30_csharp_and_dotnet.yaml

Then copy the following into the file

name:
emoji:
description: |

resources:
  - name:
    description:
    link:

Name should match the file name but in a natural form i.e. here it would be CSharp And DotNet.

The Emoji should be a valid Github Emoji you can get a list using the Github Emoji AP or a visual guide [note emoji guide will only appear after first build]

The description can be multiline and should start on the blank line after the |.

Resources is a list of resource links see above for more information.

Adding a new Group

Create a new directory in teh /data directory, this will represent a group and should be named following - i.e. 10-my-tools. , like the Categories the number represents the order in which groups should appear.

Under the group folder create a yaml file that starts 00 and then the name of the group i.e. for the one above it would 00-my-tools.yml.

name:
emoji:
description: |

Name is the name of the group, should match the name of the folder but with instead of -. Emoji, like with the categories the Emoji should be a valid Github Emoji you can get a list using the Github Emoji AP or a visual guide. Description: a short description of the group

Rebuilding the Readme

• run pnpm build to re-build the readme.

Templates

The build script uses handlebars to control the general look and feel. The templates are stored in /scripts/templates , the templates make reference to partials stored in /scripts/partials.

Partials are autoloaded by the build script and use their filename as the partial name. i.e. to include the logo partial /scripts/partials/logo.hbs you would use

{{> logo}}

Lastly some Handlebars helpers are provided in /scripts/hbs-helpers.ts they are referenced by their exported name.

• asAnchor - {{asAnchor name}} converts the name of a category into an anchor link for Github
• asEmoji - {{asEmoji name}} converts the name of an emoji to a Github markdown emoji tag

License

This repo is licensed under the Apache 2.0 license