{"id":17001616,"url":"https://github.com/shresht7/markdown-slots","last_synced_at":"2026-01-30T00:05:13.878Z","repository":{"id":37934832,"uuid":"471520686","full_name":"Shresht7/markdown-slots","owner":"Shresht7","description":"A GitHub Action to dynamically place content in markdown slots 📄","archived":false,"fork":false,"pushed_at":"2024-12-01T18:25:14.000Z","size":646,"stargazers_count":0,"open_issues_count":8,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T01:41:31.685Z","etag":null,"topics":["github-actions","markdown"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shresht7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-18T21:23:53.000Z","updated_at":"2022-03-18T21:36:57.000Z","dependencies_parsed_at":"2023-02-17T09:05:14.035Z","dependency_job_id":null,"html_url":"https://github.com/Shresht7/markdown-slots","commit_stats":{"total_commits":119,"total_committers":3,"mean_commits":"39.666666666666664","dds":"0.39495798319327735","last_synced_commit":"72312e46e3aca9e4c60e5ce723bb4081a47ec594"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shresht7%2Fmarkdown-slots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shresht7%2Fmarkdown-slots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shresht7%2Fmarkdown-slots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shresht7%2Fmarkdown-slots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shresht7","download_url":"https://codeload.github.com/Shresht7/markdown-slots/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248525775,"owners_count":21118750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-actions","markdown"],"created_at":"2024-10-14T04:25:34.052Z","updated_at":"2026-01-30T00:05:13.849Z","avatar_url":"https://github.com/Shresht7.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align='center'\u003eMarkdown Slots\u003c/h1\u003e\n\n\u003cdiv align='center'\u003e\n\n[![Release](https://img.shields.io/github/v/release/Shresht7/markdown-slots?style=for-the-badge)](https://github.com/Shresht7/markdown-slots/releases)\n[![License](https://img.shields.io/github/license/Shresht7/markdown-slots?style=for-the-badge)](./LICENSE)\n\n\u003c/div\u003e\n\n\u003cp align='center'\u003e\n\u003c!-- slot: description --\u003e\nA GitHub Action to dynamically place content in markdown slots\n\u003c!-- /slot --\u003e\n\u003c/p\u003e\n\n\u003cdiv align='center'\u003e\n\n[![Test](https://github.com/Shresht7/markdown-slots/actions/workflows/test.yml/badge.svg)](https://github.com/Shresht7/markdown-slots/actions/workflows/test.yml)\n[![Validate](https://github.com/Shresht7/markdown-slots/actions/workflows/validate.yml/badge.svg)](https://github.com/Shresht7/markdown-slots/actions/workflows/validate.yml)\n[![Action Readme](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml/badge.svg)](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml)\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\n\u003csummary align='center'\u003eTable of Contents\u003c/summary\u003e\n\n- [📖 Usage](#-usage)\n  - [1. Create markdown slots](#1-create-markdown-slots)\n  - [2. Use action in a workflow](#2-use-action-in-a-workflow)\n  - [3. Run the workflow](#3-run-the-workflow)\n- [📋 Inputs](#-inputs)\n  - [Slots](#slots)\n    - [Slot Props](#slot-props)\n  - [List of all inputs:](#list-of-all-inputs)\n- [📋 Outputs](#-outputs)\n  - [List of all outputs:](#list-of-all-outputs)\n- [📃 Workflow Examples](#-workflow-examples)\n  - [Action Readme](#action-readme)\n- [📑 License](#-license)\n\n\u003c/details\u003e\n\n---\n\n## 📖 Usage\n\n### 1. Create markdown slots\n\nTo use this action, create _slot tags_ in the markdown you wish to use as the source template.\n\n`\u003c!-- slot: myContent --\u003e` 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.\n\n`\u003c!-- /slot --\u003e` denotes the _end_ of the slot.\n\nAll content will be placed within these tags. In other words, any thing within these tags will be _overwritten_ by the slot contents.\n\n```md\n# Example Markdown\n\n\u003c!-- slot: text --\u003e\n\u003c!-- /slot --\u003e\n```\n\n\u003e Markdown-slot tags are just HTML comments, and are ignored by markdown parsers (i.e. they won't be visible in the rendered markdown).\n\n### 2. Use action in a workflow\n\nUse 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`.\n\n```yaml\n- name: markdown-slots\n  id: markdown-slots\n  uses: Shresht7/markdown-slots@v1\n  with:\n    slots: |\n      - slot: text\n        content: Hello World!\n```\n\n### 3. Run the workflow\n\nWhen 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).\n\n\u003e 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.\n\n```md\n# Example Markdown\n\n\u003c!-- slot: text --\u003e\nHello World!\n\u003c!-- /slot --\u003e\n```\n\n\u003e 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).\n\n---\n\n## 📋 Inputs\n\n### Slots\n\nThe only **required** input is `slots`. `slots` is a stringified YAML array that maps slot-names to their corresponding contents.\n\n```\n  slots: |\n    - slot: date\n      content: Today is ${{ steps.\u003cstep_id\u003e.outputs.date }}\n    - slot: month\n      content: $${{ steps.\u003cstep_id\u003e.outputs.month }}\n    - slot: year\n      content: ${{ steps.\u003cstep_id\u003e.outputs.year }}\n```\n\n\u003e \u003cstep_id\u003e is a fictional step that outputs `date`, `month` and `year`\n\n\u003e 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.\n\n#### Slot Props\n\nIn addition to `slot` and `content`, each slot input can take the following props\n\n| Property      | Description                                         |\n| ------------- | --------------------------------------------------- |\n| `prepend`     | Adds the `prepend` content before the slot-contents |\n| `append`      | Adds the `append` content after the slot-contents   |\n| `removeSlots` | Should remove the slot tags upon substitution       |\n\nfor example, to wrap some code in a code-block:\n\n```yaml\n  slots: |\n    - slot: code\n      content: console.log(content)\n      props:\n        prepend: \"```js\"\n        append: \"```\"\n```\n\nAlternatively, slot props can also be specified on the slot-tag itself. These props take priority over the ones set in the workflow.\n\n```md\n\u003c!-- slot: code, prepend: ```js, append: ``` --\u003e\n\u003c!-- /slot --\u003e\n```\n\n\u003e The slot props follow the `key: value` format and are separated by `,`.\n\n### List of all inputs:\n\n\u003c!-- slot: inputs --\u003e\n| Input          | Description                                                                  |       Default | Required |\n| :------------- | :--------------------------------------------------------------------------- | ------------: | :------: |\n| `src`          | Path to the source file with markdown-slots (can be a URL)                   | `./README.md` |          |\n| `dest`         | Desired output path for the generated content                                | `./README.md` |          |\n| `slots`        | stringified YAML array mapping slot-names to content                         |   `undefined` |     ✅    |\n| `remove-slots` | Boolean to determine if this action should remove slot tags upon replacement |       `false` |          |\n| `dry-run`      | Boolean to determine if this is a dry-run                                    |       `false` |          |\n\u003c!-- /slot --\u003e\n\n## 📋 Outputs\n\nThe 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).\n\ne.g. `${{ steps.markdown-slots.outputs.contents }}`\n\n(This assumes you set the `id` as `markdown-slots` in the [workflow step](#2-use-action-in-a-workflow)).\n\n### List of all outputs:\n\n\u003c!-- slot: outputs --\u003e\n| Output     | Description                |\n| :--------- | :------------------------- |\n| `contents` | Generated markdown content |\n\u003c!-- /slot --\u003e\n\n## 📃 Workflow Examples\n\n### Action Readme\n\nThe _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.\n\n[![Action Readme](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml/badge.svg)](https://github.com/Shresht7/markdown-slots/actions/workflows/action-readme.yml)\n\n\u003cdetails\u003e\n\n  \u003csummary\u003eClick here to see the workflow\u003c/summary\u003e\n\n  \u003cbr /\u003e\n\n  \u003c!-- slot: action-readme-workflow --\u003e\n```yaml\n# =============\n# ACTION README\n# =============\n\n# Workflow to automatically update the README with action.yml metadata\n\nname: Action Readme\n\n# Activation Events\n# =================\n\non:\n  # When the action.yml or this workflow file changes\n  push:\n    branches:\n      - main\n    paths:\n      - action.yml\n      - .github/workflows/action-readme.yml\n\n  # Manual workflow dispatch\n  workflow_dispatch:\n    inputs:\n      dry-run:\n        description: dry-run\n        required: true\n        default: \"false\"\n\n# Jobs\n# ====\n\njobs:\n  update-readme:\n    runs-on: ubuntu-latest\n    steps:\n      # Actions Checkout ✅\n      # ===================\n\n      - name: checkout\n        uses: actions/checkout@v3\n\n      # Generate Action Metadata 📜\n      # ===========================\n\n      - name: action-metadata\n        id: action-metadata\n        uses: Shresht7/action-metadata@v1\n\n      # Read Example Workflow File 📄\n      # =============================\n\n      - name: read-file\n        id: read-file\n        uses: Shresht7/read-file-action@v1\n        with:\n          path: .github/workflows/action-readme.yml\n\n      # Markdown Slots 📋\n      # =================\n\n      - name: markdown-slots\n        id: markdown-slots\n        uses: Shresht7/markdown-slots@v1\n        with:\n          slots: |\n            - slot: description\n              content: ${{ steps.action-metadata.outputs.description }}\n            - slot: inputs\n              content: ${{ steps.action-metadata.outputs.inputs-md-table }}\n            - slot: outputs\n              content: ${{ steps.action-metadata.outputs.outputs-md-table }}\n            - slot: action-readme-workflow\n              content: ${{ toJSON(steps.read-file.outputs.contents) }}\n              props:\n                prepend: \"```yaml\"\n                append: \"```\"\n\n      # Push Changes 🌎\n      # ===============\n\n      - name: check for changes\n        id: git-diff\n        run: |\n          if git diff --exit-code; then\n            echo \"::set-output name=changes_exist::false\"\n          else\n            echo \"::set-output name=changes_exist::true\"\n          fi\n\n      - name: add, commit and push\n        if: ${{ steps.git-diff.outputs.changes_exist == 'true' }}\n        run: |\n          git config user.name 'github-actions[bot]'\n          git config user.email 'github-actions[bot]@users.noreply.github.com'\n          git add .\n          git commit -m 'Update README.md 📄'\n          git push\n\n```\n\u003c!-- /slot --\u003e\n\n\u003c/details\u003e\n\n---\n\n## 📑 License\n\n\u003e [MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshresht7%2Fmarkdown-slots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshresht7%2Fmarkdown-slots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshresht7%2Fmarkdown-slots/lists"}