yivoff/commonmark-bundle

Symfony bundle integrating League CommonMark for Symfony 6.2+ applications

1.2.0 2023-12-19 13:08 UTC

Requires

• php: ^8.2
• league/commonmark: ^2.2.0
• symfony/config: ^6.3 || ^7.0
• symfony/dependency-injection: ^6.3 || ^7.0
• symfony/framework-bundle: ^6.3 || ^7.0
• symfony/http-kernel: ^6.3 || ^7.0

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8.2
• matthiasnoback/symfony-config-test: ^v5.1.0
• nyholm/symfony-bundle-test: dev-master
• roave/security-advisories: dev-master
• symfony/filesystem: ^6.3 || ^7.0
• symfony/phpunit-bridge: ^6.3 || ^7.0
• symfony/twig-bundle: ^6.3 || ^7.0
• symfony/yaml: ^6.3 || ^7.0

MIT

• Yivi

README

A Symfony 5+ bundle to integrate league/commonmark v2, allowing you to set multiple Commonmark converters.

• Requirements
• Installation
• Configuration
  • Converter type
  • Converter options
  • Converter extensions
• Using the converters
  • As services
  • Usage in templates

Requirements

This bundle requires PHP 8+ and Symfony 5+.

Installation

composer require yivoff/commonmark-bundle

If for some reason you are running without Symfony Flex, enable the bundle as usual adding Yivoff\CommonmarkBundle\YivoffCommonmarkBundle to the bundle's array.

Configuration

You'll need to enable at least one converter to use the bundle. Create a YAML configuration file at path config/packages/aymdev_commonmark.yaml. Here is an example configuration declaring 2 converters:

yivoff_commonmark:
   converters:
      commonmark:
         options:
            commonmark:
               enable_em: false

      github:
         type: github
         
      my_custom:
         type: custom
            extensions:
               - League\CommonMark\Extension\Autolink\AutolinkExtension
               - League\CommonMark\Extension\InlinesOnly\InlinesOnlyExtension

Setting up at least one converter is mandatory, but all settings are optional. By default, a converter without setting a type will be created as a CommonMark converter.

Converter type

The type key can be used to choose between a CommonMark, a GitHub Flavoured or a Custom converter.

By default, if not type is chosen, CommonMark will be chosen.

Converter options

You can use the options key holds the configuration passed to the converter, as an array.

Check the CommonMark documentation to learn more about the available options.

Converter extensions

The CommonMark and Github Flavoured have a predefined set of extensions installed, which cannot be changed.

But custom starts with no extensions, and you pick and choose which extensions you want to enable using the extensions key.

This key has no effect on github or commonmark type converters.

Using the converters

As services

Each of the defined converters is available as a service within the container.

The id is generated with the following format: yivoff_commonmark.converters.converter_name.

For the converters in the configuration example three services would be generated:

• yivoff_commonmark.converters.commonmark
• yivoff_commonmark.converters.github
• yivoff_commonmark.converters.my_custom

Additionally, the bundle registers an alias for each service, so one can use the service directly for autowiring.

Again, for the above example the registered aliases would be:

• League\CommonMark\ConverterInterface $commonmark
• League\CommonMark\ConverterInterface $github
• League\CommonMark\ConverterInterface $myCustom

Usage in templates

The bundle defines a Twig filter: commonmark.

If you have defined multiple converters, you need to pass the name of the converter you want to use:

{{ some_markdown_content|commonmark('github') }}

But If you have only one converter defined, the parameter can be omitted.

{{ some_markdown_content|commonmark }}