Convert Static Readme into Dynamic Readme

As an open-source software developer I use GitHub Repositories extensively to store my projects. I maintain over 100 projects, of which, about 85% of them have standardised content for the README.md file. That being said, I am finding it increasingly tedious to add, update or remove content in the README.md files across all my repositories because of two main challenges:

1. Templating of files: The information which is common to README.md files across all my repositories such as Sponsor, Contribute, Contact, etc., cannot be templated and inserted into the README.md files of all my projects / repositories.

2. Project / Repository-specific information: Github does not provide any repository-specific variables which can be used to dynamically insert repository information into the README.md file. As a result, repository-specific information needs to be hard-coded into the README file.

To overcome this limitation, and help developers such as myself automate this tedious task, I have created a GitHub action called “Github Action Dynamic ReadMe”. This action pulls repository-specific variables and also allows for templating of files, thereby easily creating dynamic file content for files such as README.md.

• Variables : ${{ VARIABLE_NAME }}
• Inline File Includes : <!-- include {filepath} -->
• Reusable File Includes :
  • Start : <!-- START include {filepath} -->
  • END : <!-- END include {filepath} -->

All Default vairables exposed by github actions runner can be accessed like $‎{{ GITHUB_ACTIONS }} OR $‎{{ GITHUB_ACTOR }}

Dynamic Readme Github Action Uses Repository Meta - Github Action which exposes useful metadata as environment variable and those variables can be used as template tags.

any variables exposed by Repository Meta can be accessed like below

Repository Owner : ${{ env.REPOSITORY_OWNER }}
Repository Full Name : ${{ env.REPOSITORY_FULL_NAME }}

ℹ️ Note : Any environment variable can be accessed just by using env. as prefix ${{ env.VARIABLE_NAME }}

• Relative Path : template/file.md
• Absolute path : ./template/file.md
• From Repository : {owner}/{repository}/{filepath} OR {owner}/{repository}@{branch}/{filepath}

Files are always searched from repository root path

Inline Includes : 
<!-- include template/file.md -->

Reusable Includes : 
<!-- START template/file.md -->

<!-- END template/file.md -->

Files are searched from current repository. This can come in handy when writing nested includesType a message

Inline Includes : 
<!-- include ./template/file.md -->

Reusable Includes : 
<!-- START ./template/file.md -->

<!-- END ./template/file.md -->

You can include any type of file from any repository. If you want to include a file from a Private Repository, you have to provide Github Personal Access Token INSTEAD OF Github Token in the action's workflow file.

ℹ️ If branch is not specified then default branch will be cloned

Inline Includes : 
<!-- include octocat/Spoon-Knife/README.md -->

Reusable Includes : 
<!-- START octocat/Spoon-Knife/README.md -->

<!-- END octocat/Spoon-Knife/README.md -->

Inline Includes : 
<!-- include octocat/Spoon-Knife/@master/README.md -->

Reusable Includes : 
<!-- START octocat/Spoon-Knife/@master/README.md -->

<!-- END octocat/Spoon-Knife/@master/README.md -->

blow options can be used with inline / resuable includes.

• code - [code] OR [code:{code_type}] - will print the contents of the file inside a codeblock
• blockquote - [blockquote] - will print the contents of the file inside a blockquote
• raw - [raw] OR [escape] - will print the actual contents without rendering it.

Inline Includes With Custom Markdown Below file will be included inside HTML blockquote element
<!-- include [code] template/thankyou.md --> 

Inline Includes With Custom Markdown Below file will be included inside HTML blockquote element
<!-- include [code:json] template/contents.json --> 

Reusable Includes Custom Markdown :
<!-- START [code] template/file.md -->
<!-- END [code] template/file.md -->

Reusable Includes Custom Markdown :
<!-- START [code:json] template/contents.json -->
<!-- END [code:json] template/contents.json -->

ℹ️ Inline includes can come in handy when you want to parse the data once and save it. It can also be used inside a nested include.

ℹ️ Even though Reusable includes and Inline Includes do the same work, they can come in handy when you are generating a template and saving it in the same file. It preserves the include comment which will be parsed again when re-generating the template, and the contents of the include will be updated accordingly.

name: Dynamic Template

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  update_templates:
    name: "Update Templates"
    runs-on: ubuntu-latest
    steps:
      - name: "📥  Fetching Repository Contents"
        uses: actions/checkout@main

      - name: "💾  Github Repository Metadata"
        uses: varunsridharan/action-repository-meta@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: "💫  Dynamic Template Render"
        uses: varunsridharan/action-dynamic-readme@main
        with:
          GLOBAL_TEMPLATE_REPOSITORY: {repository-owner}/{repository-name}
          files: |
            FILE.md
            FILE2.md=output_filename.md
            folder1/file.md=folder2/output.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Checkout CHANGELOG.md

If you would like to help, please take a look at the list of issues.

• MIT License © Varun Sridharan
• Code of Conduct

• ⭐ This repository if this project helped you! 😉
• Create An 🔧 Issue if you need help / found a bug

I fell in love with open-source in 2013 and there has been no looking back since! You can read more about me here. If you, or your company, use any of my projects or like what I’m doing, kindly consider backing me. I'm in this for the long run.

• ☕ How about we get to know each other over coffee? Buy me a cup for just $9.99
• ☕️☕️ How about buying me just 2 cups of coffee each month? You can do that for as little as $9.99
• 🔰 We love bettering open-source projects. Support 1-hour of open-source maintenance for $24.99 one-time?
• 🚀 Love open-source tools? Me too! How about supporting one hour of open-source development for just $49.99 one-time ?

• Follow me on 👨‍💻 Github and stay updated on free and open-source software
• Follow me on 🐦 Twitter to get updates on my latest open source projects
• Message me on 📠 Telegram
• Follow my pet on Instagram for some dog-tastic updates!

Built With ♥ By Varun Sridharan