Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shresht7/markdown-slots
A GitHub Action to dynamically place content in markdown slots 📄
https://github.com/shresht7/markdown-slots
github-actions markdown
Last synced: about 1 month ago
JSON representation
A GitHub Action to dynamically place content in markdown slots 📄
- Host: GitHub
- URL: https://github.com/shresht7/markdown-slots
- Owner: Shresht7
- License: mit
- Created: 2022-03-18T21:23:53.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-03-01T18:57:44.000Z (over 1 year ago)
- Last Synced: 2024-09-16T23:08:55.079Z (about 2 months ago)
- Topics: github-actions, markdown
- Language: TypeScript
- Homepage:
- Size: 456 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Markdown Slots
[](https://github.com/Shresht7/markdown-slots/releases)
[](./LICENSE)
A GitHub Action to dynamically place content in markdown slots
[](https://github.com/Shresht7/markdown-slots/actions/workflows/test.yml)
[](https://github.com/Shresht7/markdown-slots/actions/workflows/validate.yml)
[](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml)
Table of Contents
- [📖 Usage](#-usage)
- [1. Create markdown slots](#1-create-markdown-slots)
- [2. Use action in a workflow](#2-use-action-in-a-workflow)
- [3. Run the workflow](#3-run-the-workflow)
- [📋 Inputs](#-inputs)
- [Slots](#slots)
- [Slot Props](#slot-props)
- [List of all inputs:](#list-of-all-inputs)
- [📋 Outputs](#-outputs)
- [List of all outputs:](#list-of-all-outputs)
- [📃 Workflow Examples](#-workflow-examples)
- [Action Readme](#action-readme)
- [📑 License](#-license)
---
## 📖 Usage
### 1. Create markdown slots
To use this action, create _slot tags_ in the markdown you wish to use as the source template.
`` denotes the _start_ of the markdown slot where `myContent` is a user-defined name. This name will be [used in the workflow step](#2-use-action-in-a-workflow) to assign content to this slot.
`` denotes the _end_ of the slot.
All content will be placed within these tags. In other words, any thing within these tags will be _overwritten_ by the slot contents.
```md
# Example Markdown
```
> Markdown-slot tags are just HTML comments, and are ignored by markdown parsers (i.e. they won't be visible in the rendered markdown).
### 2. Use action in a workflow
Use this action in a workflow step and provide a YAML compatible array mapping slot-names to their corresponding content. In the example below, the text `Hello World!` is assigned to the slot named `text`.
```yaml
- name: markdown-slots
id: markdown-slots
uses: Shresht7/markdown-slots@v1
with:
slots: |
- slot: text
content: Hello World!
```
### 3. Run the workflow
When the action runs, it will write the dynamically generated content to the slot. The generated markdown will be [output](#outputs) as `contents`. The action will also write contents to the specified destination `dest` [input](#inputs).
> Writing to the dest file is a local operation. You may want to follow-up with a add-and-commit or create-pull-request workflow-step.
```md
# Example Markdown
Hello World!
```
> The default behaviour is to keep the slot tags even after content has been placed in the markdown file. This allows regeneration of slot content on subsequent runs. This can be disabled using the `remove-slots` [input](#inputs).
---
## 📋 Inputs
### Slots
The only **required** input is `slots`. `slots` is a stringified YAML array that maps slot-names to their corresponding contents.
```
slots: |
- slot: date
content: Today is ${{ steps..outputs.date }}
- slot: month
content: $${{ steps..outputs.month }}
- slot: year
content: ${{ steps..outputs.year }}
```
> is a fictional step that outputs `date`, `month` and `year`
> Note that the `|` is important. GitHub Actions expect `strings` not `yaml-objects`. The `|` signifies that `slots` is a multiline string, which is concatenated and parsed as yaml in the action.
#### Slot Props
In addition to `slot` and `content`, each slot input can take the following props
| Property | Description |
| ------------- | --------------------------------------------------- |
| `prepend` | Adds the `prepend` content before the slot-contents |
| `append` | Adds the `append` content after the slot-contents |
| `removeSlots` | Should remove the slot tags upon substitution |
for example, to wrap some code in a code-block:
```yaml
slots: |
- slot: code
content: console.log(content)
props:
prepend: "```js"
append: "```"
```
Alternatively, slot props can also be specified on the slot-tag itself. These props take priority over the ones set in the workflow.
```md
```
> The slot props follow the `key: value` format and are separated by `,`.
### List of all inputs:
| Input | Description | Default | Required |
| :------------- | :--------------------------------------------------------------------------- | ------------: | :------: |
| `src` | Path to the source file with markdown-slots (can be a URL) | `./README.md` | |
| `dest` | Desired output path for the generated content | `./README.md` | |
| `slots` | stringified YAML array mapping slot-names to content | `undefined` | ✅ |
| `remove-slots` | Boolean to determine if this action should remove slot tags upon replacement | `false` | |
| `dry-run` | Boolean to determine if this is a dry-run | `false` | |
## 📋 Outputs
The action outputs the generated contents as `contents`. You can access this in subsequent steps using [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions).
e.g. `${{ steps.markdown-slots.outputs.contents }}`
(This assumes you set the `id` as `markdown-slots` in the [workflow step](#2-use-action-in-a-workflow)).
### List of all outputs:
| Output | Description |
| :--------- | :------------------------- |
| `contents` | Generated markdown content |
## 📃 Workflow Examples
### Action Readme
The _description_, _inputs_ and _outputs_ tables of this README are placed in slots using this action! See the [action-readme workflow](./.github/workflows/action-readme.yml) for more details.
[](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml)
Click here to see the workflow
```yaml
# =============
# ACTION README
# =============
# Workflow to automatically update the README with action.yml metadata
name: Action Readme
# Activation Events
# =================
on:
# When the action.yml or this workflow file changes
push:
branches:
- main
paths:
- action.yml
- .github/workflows/action-readme.yml
# Manual workflow dispatch
workflow_dispatch:
inputs:
dry-run:
description: dry-run
required: true
default: "false"
# Jobs
# ====
jobs:
update-readme:
runs-on: ubuntu-latest
steps:
# Actions Checkout ✅
# ===================
- name: checkout
uses: actions/checkout@v3
# Generate Action Metadata 📜
# ===========================
- name: action-metadata
id: action-metadata
uses: Shresht7/action-metadata@v1
# Read Example Workflow File 📄
# =============================
- name: read-file
id: read-file
uses: Shresht7/read-file-action@v1
with:
path: .github/workflows/action-readme.yml
# Markdown Slots 📋
# =================
- name: markdown-slots
id: markdown-slots
uses: Shresht7/markdown-slots@v1
with:
slots: |
- slot: description
content: ${{ steps.action-metadata.outputs.description }}
- slot: inputs
content: ${{ steps.action-metadata.outputs.inputs-md-table }}
- slot: outputs
content: ${{ steps.action-metadata.outputs.outputs-md-table }}
- slot: action-readme-workflow
content: ${{ toJSON(steps.read-file.outputs.contents) }}
props:
prepend: "```yaml"
append: "```"
# Push Changes 🌎
# ===============
- name: check for changes
id: git-diff
run: |
if git diff --exit-code; then
echo "::set-output name=changes_exist::false"
else
echo "::set-output name=changes_exist::true"
fi
- name: add, commit and push
if: ${{ steps.git-diff.outputs.changes_exist == 'true' }}
run: |
git config user.name 'github-actions[bot]'
git config user.email 'github-actions[bot]@users.noreply.github.com'
git add .
git commit -m 'Update README.md 📄'
git push
```
---
## 📑 License
> [MIT License](./LICENSE)