Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlooped/actions-includes
Processes include HTML comments in files and inserts the included files
https://github.com/devlooped/actions-includes
actions github github-actions markdown
Last synced: 9 days ago
JSON representation
Processes include HTML comments in files and inserts the included files
- Host: GitHub
- URL: https://github.com/devlooped/actions-includes
- Owner: devlooped
- License: mit
- Created: 2022-08-04T21:01:13.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-11T00:02:25.000Z (2 months ago)
- Last Synced: 2024-09-17T02:48:58.613Z (2 months ago)
- Topics: actions, github, github-actions, markdown
- Language: PowerShell
- Size: 43 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/FUNDING.yml
- License: license.txt
Awesome Lists containing this project
README
# +Mᐁ includes
A GitHub action that resolves includes (by default in markdown files) and
embeds the included files.
## Including Content
In your content files:
```html
```
The optional `#anchor` allows including fragments of files. Anchors are
defined as:
```html
```
with an optional "closing" anchor defined exactly the same as the starting one.
If there is no closing anchor, the included content is from anchor declaration
to the end of the file. For example:
```html
[...] //some shields.io badges you use everywhere
```
Which can be included with:
```html
```
You can exclude a file from processing by having as the first (or last) line:
```html
```
## Action Usage
```
- name: +Mᐁ includes
uses: devlooped/actions-include@v1
with:
# files to include for processing, i.e. '*.md'
# Default: *.md
include: ''
# files to exclude from processing, i.e. 'header.md'
# Default: ''
exclude: ''
# whether to recurse into subdirectories
# Default: true
recurse: true|false
# Whether to validate include links. If false, a warning will be
# generated instead of an error.
# Default: true
validate: true|false
```
## Example
To run the action and automatically create a PR with the resolved includes:
```yml
on:
push:
branches:
- 'main'
paths:
- '**.md'
jobs:
includes:
runs-on: ubuntu-latest
steps:
- name: 🤘 checkout
uses: actions/checkout@v2
- name: +Mᐁ includes
uses: devlooped/actions-include@v1
- name: ✍ pull request
uses: peter-evans/create-pull-request@v3
with:
add-paths: '**.md'
base: main
branch: markdown-includes
delete-branch: true
labels: docs
commit-message: +Mᐁ includes
title: +Mᐁ includes
body: +Mᐁ includes
```
Note how you can trivially create PRs that update the changed
files so the includes are always resolved automatically whenever
you change any of the monitored files.
## How it works
You can include content from arbitrary external files with:
```Markdown
# This my actual content
# Sponsors
[](https://github.com/clarius)
[](https://github.com/KirillOsenkov)
[](https://github.com/MFB-Technologies-Inc)
[](https://github.com/decriptor)
[](https://github.com/torutek-gh)
[](https://github.com/drivenet)
[](https://github.com/davkean)
[](https://github.com/chiluap)
[](https://github.com/dgnaegi)
[](https://github.com/AshleyMedway)
[](https://github.com/Keflon)
[](https://github.com/bitbonk)
[](https://github.com/tbolon)
[](https://github.com/yrashk)
[](https://github.com/kfrancis)
[](https://github.com/wdolek)
[](https://github.com/SeanKilleen)
[](https://github.com/twenzel)
[](https://github.com/Giorgi)
[](https://github.com/mckhendry)
[](https://github.com/aritchie)
[](https://github.com/MikeCodesDotNET)
[](https://github.com/unoplatform)
[](https://github.com/dansiegel)
[](https://github.com/rbnswartz)
[](https://github.com/jeremysimmons)
[](https://github.com/jfoshee)
[](https://github.com/Mrxx99)
[](https://github.com/eajhnsn1)
[](https://github.com/mackayn)
[](https://github.com/certifytheweb)
[](https://github.com/lavahot)
[](https://github.com/mrange)
[](https://github.com/davidpetric)
[](https://github.com/richlee)
[](https://github.com/dannevesdantas)
[](https://github.com/nietras)
[](https://github.com/garywoodfine)
[](https://github.com/kristinnstefansson)
[](https://github.com/DarrenAtConexus)
[](https://github.com/kazo0)
[](https://github.com/IxTechnologies)
[](https://github.com/newrelic)
[](https://github.com/Chris-Johnston)
[](https://github.com/davidjenni)
[](https://github.com/ehonda)
[](https://github.com/Jonathan-Hickey)
[](https://github.com/okyrylchuk)
[](https://github.com/juanfranblanco)
[](https://github.com/LosManos)
[](https://github.com/MariuszKogut)
[](https://github.com/akunzai)
[](https://github.com/meisenring)
[](https://github.com/Tdue21)
[](https://github.com/jakobt)
[](https://github.com/seanalexander)
[](https://github.com/tinohager)
[](https://github.com/pedrobsaila)
[](https://github.com/ploeh)
[](https://github.com/angelobelchior)
[](https://github.com/tonyqus)
[](https://github.com/danielrmay)
[](https://github.com/BlauhausTechnology)
[](https://github.com/rcollette)
[](https://github.com/bngv)
[](https://github.com/KenBonny)
[](https://github.com/SimonCropp)
[](https://github.com/sponsors/devlooped)
[Learn more about GitHub Sponsors](https://github.com/sponsors)
```
The action is idempotent, so it is safe for it to run on pushes of the
same files it changed via the includes (since no further changes will
be detected).
> NOTE: the included path must be relative to the including file.
## Limitations
* Nested includes are not supported for now (the `include` keyword inside the HTML
comment "directive" will be stripped on inclusion).
* File processing order matches what the following equivalent command on the
working directory returns via PowerShell:
```
pwsh> gci -include [include] -exclude [exclude] [-recurse]
```
This knowledge can be used to workaround the nested includes limitation by
running the action multiple times with different sets of files.