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"}}