noem/composer-file-embed

description

Installs: 620

Dependents: 6

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 1

Type:composer-plugin

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

This package is auto-updated.

Last update: 2024-06-17 14:19:15 UTC


README

Composer File Embed

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