README Template#

Add GitHub data to your README.md, or any other file.

A GitHub action that provides template strings that are replaced with their respective values when the action runs.

By default, it takes TEMPLATE.md and outputs README.md.

Inputs#

Example usage#

Check out EXAMPLE_TEMPLATE.md and EXAMPLE_OUTPUT.md for more examples and their outputs.

Workflow:

name: Readme Template
on:
  schedule:
    - cron: '0 */2 * * *' # every 2 hours
  push:
    branches: [ master ]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
    - name: Generate README.md
      uses: probablykasper/readme-template-action@v1
      with:
        token: ${{ secrets.README_TEMPLATE_TOKEN }}
        template: TEMPLATE.md
        output: README.md
    - name: Update README.md
      run: |
        if [[ "$(git status --porcelain)" != "" ]]; then
          git config user.name "GitHub Action"
          git config user.email "action@github.com"
          git add .
          git commit -m "Auto-update README.md"
          git push
        fi

TEMPLATE.md:

My most starred repos:
| ⭐️Stars   | 📦Repo    | 📚Description |
| --------- | ----------- | -------------- |
{{ loop 3_MOST_STARRED_REPOS }}
| {{ REPO_STARS }} | [{{ REPO_FULL_NAME }}]({{ REPO_URL }}) | {{ REPO_DESCRIPTION }} |
{{ end 3_MOST_STARRED_REPOS }}

This generates the following output in my case:

My most starred repos:

Variables#

Normal variables you can put into your template file#

Variables you can put inside repo loops#

Loops#

These are the built-in loops you can use. Data is only fetched for loops you use.

first: 3,
privacy: PUBLIC,
ownerAffiliations:[OWNER],
orderBy: { field:STARGAZERS, direction: DESC }

first: 3,
privacy: PUBLIC,
ownerAffiliations:[OWNER],
orderBy: { field:CREATED_AT, direction: DESC }

first: 3,
privacy: PUBLIC,
ownerAffiliations:[OWNER],
orderBy: { field:PUSHED_AT, direction: DESC }

Advanced usage#

Check out EXAMPLE_TEMPLATE.md and EXAMPLE_OUTPUT.md to see examples and their outputs.

For advanced usage, add a code block like this to your template:

```js
// {{ TEMPLATE: }}
module.exports = {
    // ... custom vairables/loops
}
// {{ :TEMPLATE }}

List specific repos#

Get a list of specific repos

  CUSTOM_PINNED_REPOS: {
    type: 'specificRepos',
    repos: [ 'vidl', 'golang/go', 'probablykasper/embler' ],
  },

Repos with custom parameters#

Get repos using custom parameters:

  "2_MOST_STARRED_REPOS": {
    type: 'repos',
    params: `
      first: 2,
      privacy: PUBLIC,
      ownerAffiliations:[OWNER],
      orderBy: { field:STARGAZERS, direction: DESC },
    `,
  },

Modify variables#

Add a modifyVariables function to overwrite/add variables:

  CUSTOM_PINNED_REPOS: {
    type: 'specificRepos',
    repos: [ 'vidl' ],
    modifyVariables: function(repo, moment, user) {
      repo.REPO_CREATED_MYDATE = moment(repo.REPO_CREATED_TIMESTAMP).format('YYYY MMMM Do')
      return repo
    },
  },

Custom queries#

  LATEST_VIDL_RELEASE: {
    type: 'customQuery',
    loop: false,
    query: async (octokit, moment, user) => {
      // You can do anything  you want with the GitHub API here.
      const result = await octokit.graphql(`
        query {
          repository(name: "vidl", owner: "${user.USERNAME}") {
            releases(last: 1) {
              edges {
                node {
                  url
                  publishedAt
                  tagName
                }
              }
            }
          }
        }
      `)
      const release = result.repository.releases.edges[0].node
      const date = new Date(release.publishedAt)
      // We have `loop: false`, so we return an object.
      // If we had `loop: true`, we would return an array of objects.
      return {
        VIDL_RELEASE_TAG: release.tagName,
        VIDL_RELEASE_URL: release.url,
        VIDL_RELEASE_WHEN: moment(release.publishedAt).fromNow(),
      }
    }
  }

Dev instructions#

First, to get started:

1. Install Node.js
2. Run npm install
3. Go here to generate a GitHub personal access token with the read:user scope.
4. Create a .env file like this, with your token:

INPUT_TOKEN=mytoken
INPUT_TEMPLATE=EXAMPLE_TEMPLATE.md
INPUT_OUTPUT=EXAMPLE_OUTPUT.md

Now you can test the action by running the following command:

npm run test

Build:

npm run build