Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/varunsridharan/action-dynamic-readme
~ Dynamic ReadME Generator ~
https://github.com/varunsridharan/action-dynamic-readme
action actions dynamic dynamic-markdown dynamic-readme github github-action markdown readme readme-bolierplate readme-generator readme-template
Last synced: 12 days ago
JSON representation
~ Dynamic ReadME Generator ~
- Host: GitHub
- URL: https://github.com/varunsridharan/action-dynamic-readme
- Owner: varunsridharan
- License: mit
- Created: 2020-10-17T11:07:36.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2021-11-23T01:09:40.000Z (almost 3 years ago)
- Last Synced: 2024-10-03T12:23:30.408Z (about 1 month ago)
- Topics: action, actions, dynamic, dynamic-markdown, dynamic-readme, github, github-action, markdown, readme, readme-bolierplate, readme-generator, readme-template
- Language: PHP
- Homepage: https://github.com/marketplace/actions/dynamic-readme
- Size: 90.8 KB
- Stars: 43
- Watchers: 2
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- project-awesome - varunsridharan/action-dynamic-readme - ~ Dynamic ReadME Generator ~ (PHP)
README
# Dynamic ReadMe - ***Github Action***
Convert Static Readme into Dynamic Readme
## Motivation
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.
### Solution:
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.
## ⚙️ Configuration
| Option | Description | Default |
| --- | --- | --- |
| `FILES` | list of files that should be compiled. | `false`
| `DELIMITER` | you can change the default **DELIMITER** if it causes issue with your data. | `${{ }}`
| `GLOBAL_TEMPLATE_REPOSITORY` | you can set a global repository template where all the files are stored. | `false`
| `committer_name` | Specify the committer name | `Dynamic Readme` |
| `committer_email` | Specify the committer email | `[email protected]` |
| `commit_message` | set a custom commit message | `💬 - File Rebuilt - Github Action Runner : ${GITHUB_RUN_NUMBER}` |
| `confirm_and_push` | Commit the changes and push directly to repository | `true` |
## :writing_hand: Syntax
* Variables : `${{ VARIABLE_NAME }}`
* Inline File Includes : ``
* Reusable File Includes :
* Start : ``
* END : ``
### Variables
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**](https://github.com/varunsridharan/action-repository-meta) 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
```markdown
Repository Owner : ${{ env.REPOSITORY_OWNER }}
Repository Full Name : ${{ env.REPOSITORY_FULL_NAME }}
```
> :information_source: **Note :** Any environment variable can be accessed just by using `env.` as prefix `${{ env.VARIABLE_NAME }}`
### File Includes
#### Source Options
* Relative Path : `template/file.md`
* Absolute path : `./template/file.md`
* From Repository : `{owner}/{repository}/{filepath}` OR `{owner}/{repository}@{branch}/{filepath}`
#### Relative Path Syntax
Files are always searched from repository root path
```markdown
Inline Includes :
Reusable Includes :
```
#### Absolute path Syntax
Files are searched from current repository. This can come in handy when writing nested includesType a message
```markdown
Inline Includes :
Reusable Includes :
```
#### From Repository Syntax
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.
> :information_source: If branch is not specified then default branch will be cloned
##### Without Branch
```markdown
Inline Includes :
Reusable Includes :
```
##### Custom Branch
```markdown
Inline Includes :
Reusable Includes :
```
#### Builtin Markdown Handlers
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.
##### Example
```markdown
Inline Includes With Custom Markdown Below file will be included inside HTML blockquote element
Inline Includes With Custom Markdown Below file will be included inside HTML blockquote element
Reusable Includes Custom Markdown :
Reusable Includes Custom Markdown :
```
> :information_source: **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.
>
> :information_source: 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.
### Pull Request Support
This action modifies the files, creates a commit and uploads them directly to the default branch of the repository.
If the default branch of the repository is protected by the rule `Require a pull request before merging` then you will need to set the option `confirm_and_push: false` so that the commit is not made and the changes are not uploaded to the default branch.
``` yaml
- 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
confirm_and_push: false # Important if use "Require a pull request before merging" rule
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
In addition to the previous configuration, it is necessary to use other actions to be able to confirm the changes and generate a Pull Request towards the default branch
``` yaml
- name: "📥 Fetching Repository Contents"
uses: actions/checkout@main
- 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
confirm_and_push: false # Important if use "Require a pull request before merging" rule
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Create pull request
uses: peter-evans/create-pull-request@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
```
Thanks to this configuration, the necessary files can be dynamically generated by adding them to a different branch that then we can merge with the default branch, complying with the rule `Require a pull request before merging`.
Check out the example workflow (Pull Request Support) for a more advanced configuration
---
For live Demo Please Check Demo Repository
---
## 🚀 Example Workflow File
```yaml
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 }}
```
## 🚀 Example Workflow File (Pull Request Support)
```yaml
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
committer_name: github-actions[bot]
committer_email: github-actions[bot]@users.noreply.github.com
commit_message: 'docs: update readme file [skip ci]'
confirm_and_push: false
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Create pull request
id: cpr
uses: peter-evans/create-pull-request@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: 'docs: documentation files updated [skip ci]'
committer: github-actions[bot]
author: github-actions[bot]
signoff: false
branch: github-actions/repository-maintenance
delete-branch: true
title: Update documentation files
body: All documentation files has been updated to last recent version
labels: |
skip-changelog
docs
- name: Enable pull request automerge
if: steps.cpr.outputs.pull-request-operation == 'created'
uses: peter-evans/enable-pull-request-automerge@v1
with:
token: ${{ secrets.PAT }}
pull-request-number: ${{ steps.cpr.outputs.pull-request-number }}
- name: Auto approve
if: steps.cpr.outputs.pull-request-operation == 'created'
uses: juliangruber/approve-pull-request-action@v1
with:
github-token: ${{ secrets.PAT }}
number: ${{ steps.cpr.outputs.pull-request-number }}
```
---
## 📝 Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
[Checkout CHANGELOG.md](https://github.com/varunsridharan/action-dynamic-readme/blob/main/CHANGELOG.md)
## 🤝 Contributing
If you would like to help, please take a look at the list of [issues](https://github.com/varunsridharan/action-dynamic-readme/issues/).
## 📜 License & Conduct
- [**MIT License**](https://github.com/varunsridharan/action-dynamic-readme/blob/main/LICENSE) © [Varun Sridharan](website)
- [Code of Conduct](https://github.com/varunsridharan/.github/blob/main/CODE_OF_CONDUCT.md)
## 📣 Feedback
- ⭐ This repository if this project helped you! :wink:
- Create An [🔧 Issue](https://github.com/varunsridharan/action-dynamic-readme/issues/) if you need help / found a bug
## 💰 Sponsor
[I][twitter] fell in love with open-source in 2013 and there has been no looking back since! You can read more about me [here][website].
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**][buymeacoffee]
- ☕️☕️ How about buying me just 2 cups of coffee each month? You can do that for as little as [**$9.99**][buymeacoffee]
- 🔰 We love bettering open-source projects. Support 1-hour of open-source maintenance for [**$24.99 one-time?**][paypal]
- 🚀 Love open-source tools? Me too! How about supporting one hour of open-source development for just [**$49.99 one-time ?**][paypal]
[paypal]: https://sva.onl/paypal
[buymeacoffee]: https://sva.onl/buymeacoffee
[twitter]: https://sva.onl/twitter/
[website]: https://sva.onl/website/
## Connect & Say 👋
- **Follow** me on [👨💻 Github][github] and stay updated on free and open-source software
- **Follow** me on [🐦 Twitter][twitter] to get updates on my latest open source projects
- **Message** me on [📠 Telegram][telegram]
- **Follow** my pet on [Instagram][sofythelabrador] for some _dog-tastic_ updates!
[sofythelabrador]: https://www.instagram.com/sofythelabrador/
[github]: https://sva.onl/github/
[twitter]: https://sva.onl/twitter/
[telegram]: https://sva.onl/telegram/
---
Built With ♥ By Varun Sridharan
---