Merge pull request #421 from CPS-IT/docs/admonitions

[DOCS] Use admonitions and emoji characters in documentation

README.md

@@ -12,25 +12,25 @@
 [![PHP Version Require](http://poser.pugx.org/cpsit/frontend-asset-handler/require/php)](https://packagist.org/packages/cpsit/frontend-asset-handler)
 [![License](http://poser.pugx.org/cpsit/frontend-asset-handler/license)](LICENSE.md)
 
-:package: [Packagist](https://packagist.org/packages/cpsit/frontend-asset-handler) |
-:floppy_disk: [Repository](https://github.com/CPS-IT/frontend-asset-handler) |
-:bug: [Issue tracker](https://github.com/CPS-IT/frontend-asset-handler/issues)
+📦 [Packagist](https://packagist.org/packages/cpsit/frontend-asset-handler) |
+💾 [Repository](https://github.com/CPS-IT/frontend-asset-handler) |
+🐛 [Issue tracker](https://github.com/CPS-IT/frontend-asset-handler/issues)
 
 </div>
 
 A Composer library that downloads and extracts Frontend assets to a dedicated path in PHP projects.
 All Frontend assets are configured through an `assets.json` file and can be easily maintained by
 a dedicated CLI application.
 
-## :rocket: Features
+## 🚀 Features
 
 * Command-line application to fetch Frontend assets
 * Asset configuration via `assets.json` file
 * Automated integration into CI systems
 * Easy extensible by custom asset providers and processors
 * Designed for dependency injection
 
-## :fire: Getting started
+## 🔥 Getting started
 
 1. [Install](docs/installation.md) the library:
 
@@ -50,7 +50,7 @@ a dedicated CLI application.
    vendor/bin/frontend-assets fetch
    ```
 
-## :book: Documentation
+## 📖 Documentation
 
 * [Installation](docs/installation.md)
 * [Usage](docs/usage/index.md)
@@ -76,14 +76,14 @@ a dedicated CLI application.
 * [Dependency injection](docs/dependency-injection.md)
 * [Migration](docs/migration.md)
 
-## :technologist: Contributing
+## 🧑‍💻 Contributing
 
 Please have a look at [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-## :gem: Credits
+## 💎 Credits
 
 [Direct download icons created by Pixel perfect - Flaticon](https://www.flaticon.com/free-icons/direct-download)
 
-## :star: License
+## ⭐ License
 
 This project is licensed under [GNU General Public License 3.0 (or later)](LICENSE.md).

docs/components/processors.md

@@ -13,7 +13,8 @@ It supports the following additional configuration:
 Base path within the fetched asset archive that should be extracted to the configured
 path. Only files within this path are extracted, all other files are ignored.
 
-> :bulb: You can set this to an empty value to extract all files.
+> [!TIP]
+> You can set this to an empty value to extract all files.
 
 * Required: **no**
 * Default: **`''`** _(= extract all files)_

docs/components/providers.md

@@ -15,7 +15,8 @@ With this Provider, local paths may be used as Frontend asset source. An additio
 command can be specified that is executed prior to validating the local path, e.g.
 to initialize a new build or archive a list of files and directories.
 
-> :bulb: The local path itself is configured by the [`url`](#url) configuration.
+> [!NOTE]
+> The local path itself is configured by the [`url`](#url) configuration.
 
 It supports the following additional configuration:
 
@@ -65,4 +66,5 @@ the following special placeholders:
 }
 ```
 
-> :warning: The resolved URL must be an existing path on the local filesystem.
+> [!WARNING]
+> The resolved URL must be an existing path on the local filesystem.

docs/config/environments.md

@@ -21,9 +21,10 @@ object, generated by [`MapFactory::crateFromArray()`](../../src/Asset/Environmen
 Each mapping must include a branch pattern and a corresponding
 configuration for an [environment transformer](../components/environment-transformers.md).
 
-:bulb: The branch pattern can be either a regular expression with
-delimiter `/` or any other string that is processable by the
-[`fnmatch`][1] function.
+> [!TIP]
+> The branch pattern can be either a regular expression with
+> delimiter `/` or any other string that is processable by the
+> [`fnmatch`][1] function.
 
 * Required: **no**
 * Default: **–**
@@ -77,7 +78,8 @@ resolves to the following mapping table:
 _<sup>1)</sup> If a specific version number is given, then exactly this version number is
 also requested as the asset environment. In this case, no mapping takes place._
 
-> :bulb: You can extend or completely exchange the default map by your needs.
+> [!TIP]
+> You can extend or completely exchange the default map by your needs.
 
 [1]: https://www.php.net/manual/en/function.fnmatch.php
 [2]: https://packagist.org/packages/ondram/ci-detector

docs/dependency-injection.md

@@ -31,8 +31,9 @@ achieved by adding a `services` array to your [assets configuration file](config
 }
 ```
 
-:bulb: **Note:** Only `yaml` and `php` files are supported. Take a look at the
-[official Symfony documentation][1] to get an overview about service configuration.
+> [!NOTE]
+> Only `yaml` and `php` files are supported. Take a look at the
+> [official Symfony documentation][1] to get an overview about service configuration.
 
 ## Service container
 
@@ -50,9 +51,10 @@ $containerFactory = new DependencyInjection\ContainerFactory($configFile);
 $container = $containerFactory->get();
 ```
 
-:bulb: **Note:** You must specify the path to a valid [assets configuration file](config/index.md).
-Otherwise, a failsafe container will be created which can only be used for some low-level commands
-(see the following section).
+> [!WARNING]
+> You must specify the path to a valid [assets configuration file](config/index.md).
+> Otherwise, a failsafe container will be created which can only be used for some low-level commands
+> (see the following section).
 
 ### Failsafe container
 

docs/usage/api-usage.md

@@ -56,7 +56,7 @@ $asset = $handler->handle($source, $target/*, $strategy */);
 echo 'Assets downloaded and extracted to ' . $asset->getProcessedTargetPath();
 ```
 
-:bulb: If you prefer configuration with a config file instead, you can load
+💡 If you prefer configuration with a config file instead, you can load
 and parse this file as follows:
 
 ```php

docs/usage/cli-config-assets.md

@@ -11,8 +11,9 @@ from the given configuration file.
 
 Define the path to the assets configuration file.
 
-> :warning: In previous versions, configuration could also be added to the `composer.json`
-> file. This is no longer possible. You need to define all settings in a separate file
+> [!NOTE]
+> In previous versions, configuration could also be added to the `composer.json` file.
+> This is no longer possible. You need to define all settings in a separate file
 > and pass it via this command option.
 
 * Required: **yes**
@@ -22,7 +23,8 @@ Define the path to the assets configuration file.
 
 Use this command option to unset configuration at the given path.
 
-> :warning: This option cannot be used in combination with the `--validate` option and the
+> [!NOTE]
+> This option cannot be used in combination with the `--validate` option and the
 > `newValue` argument.
 
 * Required: **no**
@@ -33,7 +35,8 @@ Use this command option to unset configuration at the given path.
 This option can be used to validate asset configuration provided by the given assets
 configuration file.
 
-> :warning: It cannot be used in combination with the `--unset` option and the `newValue`
+> [!NOTE]
+> This option cannot be used in combination with the `--unset` option and the `newValue`
 > argument.
 
 * Required: **no**
@@ -51,7 +54,8 @@ Treat the value passed with `newValue` argument as JSON.
 Run [value processors](../components/placeholder-processors.md) when reading or
 validating asset configuration.
 
-> :warning: This option has no effect with the `newValue` argument.
+> [!NOTE]
+> This option has no effect with the `newValue` argument.
 
 * Required: **no**
 * Default: **no**
@@ -69,7 +73,8 @@ file. Path segments should be combined with a slash (`/`), e.g. `0/source/versio
 Define the new value to be written at the given path in the configuration file. If
 you leave this argument out, the current value at the given path will be returned.
 
-> :warning: This argument cannot be used in combination with the `--unset` and
+> [!NOTE]
+> This argument cannot be used in combination with the `--unset` and
 > `--validate` options.
 
 * Required: **no**

docs/usage/cli-fetch-assets.md

@@ -11,8 +11,9 @@ This command fetches Frontend assets for the given branch using the provided
 
 Define the path to the assets configuration file.
 
-> :warning: In previous versions, configuration could also be added to the `composer.json`
-> file. This is no longer possible. You need to define all settings in a separate file
+> [!NOTE]
+> In previous versions, configuration could also be added to the `composer.json` file.
+> This is no longer possible. You need to define all settings in a separate file
 > and pass it via this command option.
 
 * Required: **yes**
@@ -40,7 +41,8 @@ specific Frontend assets are available.
 The branch to be used to resolve the requested asset environment that should be known
 by the requested provider.
 
-> :bulb: If no branch is given, the currently checked out branch is used.
+> [!NOTE]
+> If no branch is given, the currently checked out branch is used.
 
 * Required: **no**
 * Default: **current branch** (see [branch determination logic](../config/environments.md#branch-determination-logic))

docs/usage/cli-init-config.md

@@ -8,14 +8,16 @@ With this command, a new asset configuration file can be created. An interactive
 tour guides through various configuration options for asset source and target.
 In the end, a new config file is created.
 
-:warning: This command can only be used in interactive mode.
+> [!NOTE]
+> This command can only be used in interactive mode.
 
 ## `-c|--config`
 
 Define the path to the assets configuration file.
 
-> :warning: In previous versions, configuration could also be added to the `composer.json`
-> file. This is no longer possible. You need to define all settings in a separate file
+> [!NOTE]
+> In previous versions, configuration could also be added to the `composer.json` file.
+> This is no longer possible. You need to define all settings in a separate file
 > and pass it via this command option.
 
 * Required: **yes**

docs/usage/cli-inspect-assets.md

@@ -16,8 +16,9 @@ asset source location.
 
 Define the path to the assets configuration file.
 
-> :warning: In previous versions, configuration could also be added to the `composer.json`
-> file. This is no longer possible. You need to define all settings in a separate file
+> [!NOTE]
+> In previous versions, configuration could also be added to the `composer.json` file.
+> This is no longer possible. You need to define all settings in a separate file
 > and pass it via this command option.
 
 * Required: **yes**
@@ -37,7 +38,8 @@ to assure asset sources are up-to-date before fetching them.
 The branch to be used to resolve the requested asset environment that should be known
 by the requested provider.
 
-> :bulb: If no branch is given, the currently checked out branch is used.
+> [!NOTE]
+> If no branch is given, the currently checked out branch is used.
 
 * Required: **no**
 * Default: **current branch** (see [branch determination logic](../config/environments.md#branch-determination-logic))