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.
| name | required | type | default | description |
|---|---|---|---|---|
| token | yes | string | GitHub personal access token used to fetch data. Pass a secret by for instance using ${{ secrets.README_TEMPLATE_TOKEN }}. Go here to generate one with the read:user scope |
|
| template | yes | string | "TEMPLATE.md" |
Template file path |
| readme | yes | string | "README.md" |
Output file path |
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
fiTEMPLATE.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:
| ⭐️Stars | 📦Repo | 📚Description |
|---|---|---|
| 10 | probablykasper/chester-syntax | A pretty Atom syntax theme based on Lonely Planet colours |
| 4 | probablykasper/homebrew-tap | My Homebrew casks and formulas |
| 2 | probablykasper/cryp | Cryptocurrency portfolio tracker |
| 1 | probablykasper/notifier | Flutter app for scheduling notifications |
| 1 | probablykasper/colorboy | Easy terminal coloring for Node.js, macOS/Linux |
| Variable | Example |
|---|---|
| {{ USERNAME }} | probablykasper |
| {{ NAME }} | Kasper |
| {{ EMAIL }} | email@example.com |
| {{ USER_ID }} | MDQ6VXNlcjExMzE1NDky |
| {{ BIO }} | Fullstack developer from Norway |
| {{ COMPANY }} | Microscopicsoft |
| {{ LOCATION }} | Norway |
| {{ TWITTER_USERNAME }} | probablykasper |
| {{ AVATAR_URL }} | https://avatars0.githubusercontent.com/u/11315492?u=c501da00e9b817ffc78faab6c630f236ac2738cf&v=4 |
| {{ WEBSITE_URL }} | https://kasper.space/ |
| {{ SIGNUP_TIMESTAMP }} | 2015-03-04T14:48:35Z |
| {{ SIGNUP_DATE }} | March 4th 2015 |
| {{ SIGNUP_DATE2 }} | 2015-03-04 |
| {{ SIGNUP_YEAR }} | 2015 |
| {{ SIGNUP_AGO }} | 5 years ago |
| {{ TOTAL_REPOS_SIZE_KB }} | 707453 |
| {{ TOTAL_REPOS_SIZE_MB }} | 707.5 |
| {{ TOTAL_REPOS_SIZE_GB }} | 0.71 |
| {{ TOTAL_REPOSITORIES }} | 46 |
| {{ REPO_FULL_NAME }} | probablykasper/readme-template-action |
| {{ REPO_NAME }} | readme-template-action |
| Variable | Example |
|---|---|
| {{ REPO_NAME }} | cpc |
| {{ REPO_FULL_NAME }} | probablykasper/cpc |
| {{ REPO_DESCRIPTION }} | Text calculator with support for units and conversion |
| {{ REPO_URL }} | https://github.com/probablykasper/cpc |
| {{ REPO_HOMEPAGE_URL }} | https://rust-lang.org/ |
| {{ REPO_CREATED_TIMESTAMP }} | 2019-12-05T22:45:04Z |
| {{ REPO_PUSHED_TIMESTAMP }} | 2020-08-20T20:13:22Z |
| {{ REPO_FORK_COUNT }} | 2 |
| {{ REPO_ID }} | MDEwOlJlcG9zaXRvcnkyMjYyMDE5NTU= |
| {{ REPO_CREATED_DATE }} | December 5th 2019 |
| {{ REPO_CREATED_DATE2 }} | 2019-12-05 |
| {{ REPO_CREATED_YEAR }} | 2019 |
| {{ REPO_CREATED_AGO }} | 9 months ago |
| {{ REPO_PUSHED_DATE }} | August 20th 2020 |
| {{ REPO_PUSHED_DATE2 }} | 2020-08-20 |
| {{ REPO_PUSHED_YEAR }} | 2020 |
| {{ REPO_PUSHED_AGO }} | 3 days ago |
| {{ REPO_STARS }} | 5 |
| {{ REPO_LANGUAGE }} | Rust |
| {{ REPO_OWNER_USERNAME }} | probablykasper |
| {{ REPO_SIZE_KB }} | 1268285 |
| {{ REPO_SIZE_MB }} | 1268.3 |
| {{ REPO_SIZE_GB }} | 1.27 |
These are the built-in loops you can use. Data is only fetched for loops you use.
| Loop | Type | Description |
3_MOST_STARRED_REPOS |
repos |
Fetches your 3 most starred repos.
Uses the following parameters:
first: 3, |
3_NEWEST_REPOS |
repos |
Fetches your 3 most starred repos.
Uses the following parameters:
first: 3, |
3_RECENTLY_PUSHED_REPOS |
repos |
Fetches your 3 most starred repos.
Uses the following parameters:
first: 3, |
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 }}Get a list of specific repos
CUSTOM_PINNED_REPOS: {
type: 'specificRepos',
repos: [ 'vidl', 'golang/go', 'probablykasper/embler' ],
},Get repos using custom parameters:
"2_MOST_STARRED_REPOS": {
type: 'repos',
params: `
first: 2,
privacy: PUBLIC,
ownerAffiliations:[OWNER],
orderBy: { field:STARGAZERS, direction: DESC },
`,
},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
},
}, 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(),
}
}
}First, to get started:
- Install Node.js
- Run
npm install - Go here to generate a GitHub personal access token with the
read:userscope. - Create a
.envfile like this, with your token:
INPUT_TOKEN=mytoken
INPUT_TEMPLATE=EXAMPLE_TEMPLATE.md
INPUT_OUTPUT=EXAMPLE_OUTPUT.mdNow you can test the action by running the following command:
npm run testBuild:
npm run build