noem/composer-file-embed

description

dev-master 2022-04-10 00:01 UTC

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

MIT

• biont

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.

Key	Type	Required	Example	Comment
path	string	yes	./src/MyClass.php	Path or URL to the text you want to embed
lang	string	no	php	Specify the language in case in it cannot be (correctly) identified
match	string	no	class.*}	Include only the matching parts of the specified file. Default: ^.*$

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.