Awesome

A helper to generate the READE file automatically.

Get started

Install it via hd:

hd i yaml-readme

Usage

# yaml-readme -h
Usage:
  yaml-readme [flags]

Flags:
  -h, --help              help for yaml-readme
  -p, --pattern string    The glob pattern with Golang spec to find files (default "items/*.yaml")
  -t, --template string   The template file which should follow Golang template spec (default "README.tpl")

Available variables:

Name	Usage
`filename`	The filename of a particular item file. For example, `items/good.yaml`, the filename is `good`.
`parentname`	The parent directory name. For example, `items/good.yaml`, the parent name is `items`.
`fullpath`	The related file path of each items.

Available functions

Name	Usage	Description
`printHelp`	`{{printHelp 'hd'}}`	Print the help text of a command
`printToc`	`{{printToc}}`	Print the TOC of the template file
`printContributors`	`{{printContributors "linuxsuren" "yaml-readme"}}`	Print all the contributors of an repository
`printStarHistory`	`{{printStarHistory "linuxsuren" "yaml-readme"}}`	Print the star history of an repository
`printVisitorCount`	`{{printVisitorCount "repo-id"}}`	Print the visitor count chart of an repository
`printPages`	`{{printPages "linuxsuren"}}`	Print all the repositories that pages enabled
`render`	`{{render true}}`	Make the value be readable, turn `true` to `:white_check_mark:`
`gh`	`{{gh "linuxsuren" true}}`	Render a GitHub user to be a link
`ghs`	`{{ghs "linuxsuren, linuxsuren" ","}}`	Render multiple GitHub users to be links
`link`	`{{link "text" "link"}}`	Print a Markdown style link
`linkOrEmpty`	`{{linkOrEmpty "text" "link"}}`	Print a Markdown style link or empty if text is none
`ghEmoji`	`{{ghEmoji "linuxsuren"}}`	Print a Markdown style link with Emoji

Want to use more powerful functions? Please feel free to see also Sprig. You could use all functions from both built-in and Sprig.

Ignore particular items

In case you want to ignore some particular items, you can put a key ignore with value true. Let's see the following sample:

name: rick
ignore: true

Use in GitHub actions

You could copy the following sample YAML, and change some variables according to your needs.

name: generator

on:
  push:
    branches: [ master ]

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, 'ci skip')"

    steps:
      - uses: actions/checkout@v3
      - name: Update readme
        uses: linuxsuren/yaml-readme@v0.0.6
        env:
          GH_TOKEN: ${{ secrets.GH_SECRETS }}
        with:
          pattern: 'config/*/*.yml'
          username: linuxsuren
          org: linuxsuren
          repo: hd-home

Samples

Below is a simple template sample:

The total number of tools is: {{len .}}
| Name | Latest | Download |
|---|---|---|
{{- range $val := .}}
| {{$val.name}} | {{$val.latest}} | {{$val.download}} |
{{- end}}

Below is a grouped data sample:

{{- range $key, $val := .}}
Year: {{$key}}
| Name | Age |
|---|---|
{{- range $item := $val}}
| {{$item.name}} | {{$item.age}} |
{{- end}}
{{end}}

You could use the following command to render it:

yaml-readme --group-by year

Assume there is a complex YAML like this:

metadata:
  annotations:
    group/key: 'a value'

then you can use the following template:

{{index $item.metadata.annotations "group/key"}}