noem / composer-file-embed
description
Installs: 636
Dependents: 6
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 1
Type:composer-plugin
Requires
- composer-plugin-api: ^2.0
- justinrainbow/json-schema: ^5.2
- symfony/finder: ^5.3
- symfony/yaml: ^5.3
Requires (Dev)
- composer/composer: ^2.0
- mockery/mockery: ^1.4
- nunomaduro/collision: ^5.8
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.6
This package is auto-updated.
Last update: 2024-10-17 15:09:04 UTC
README
A composer plugin that allows embedding files as code snippets in your markdown docs
Installation
Install this package via composer:
composer require noem/composer-file-embed
Usage
The plugin parses Markdown's "hidden link syntax" which can otherwise used for comments, in a custom format. This allows us to define embeds without these definitions showing up in the generated output. The following formats are all valid, so in case your markdown processor trips over one, you can try a different format:
[embed]:# (path: filepathOrURL, lang: language, match: '[a-zA-Z]') [embed]:<> (path: filepathOrURL, lang: language, match: '[a-zA-Z]') [embed]:# "path: filepathOrURL, lang: language, match: '[a-zA-Z]'"
The config inside the parentheses is actually an inline YAML string, so commas and spaces are important. Don't forget to
quote your config when encessary. Only the path
is required.
Since only the path
is required, you can simply do
[embed]:# (path: path/to/file.php)
...to embed a full file.
Check out the Examples page for more detailed examples and use-cases.
After you made changes to your documents, use the new CLI command to process all *.md
files in the current directory.
It will recurse into subdirectories, but exclude the vendor/
folder.
In your project directory, run:
composer embed-files
Notes
When using Jekyll / GH-Pages, the comment markup can break if you use quotes in your YAML. The result is that
the [embed]
definition is visible on GH Pages despite not being rendered on GitHub itself. Try a different format
then. For example, if you need to pass a single-quoted regex pattern, the use of double quotes in the comment is known
to work:
[embed]:# "path: ./foo.md, match: '##\sThanks.*$'"
Thanks
- @campoy for campoy/embed which was a huge inspiration.