Skip to content

A helper to generate the READE file automatically from YAML-based metadata files.

License

Notifications You must be signed in to change notification settings

LinuxSuRen/yaml-readme

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

codecov vscode

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