Custom Directives

Directives are designed to be an extension mechanism for reStructuredText. It enables you to add custom functionality to reStructuredText without having to add new custom syntaxes.

Directive Class

You can write your own directives by defining a class that extends the Doctrine\RST\Directives\Directive class and defines the method getName() that returns the directive name.

You can then implement one of the following methods:

processAction() if your directive simply tweak the document without modifying the nodes
processNode() if your directive is adding a node
process() if your directive is tweaking the node that just follows it

See Directive.php for more information.

Example Directive

namespace App\RST\Directives;

use Doctrine\RST\Nodes\Node;
use Doctrine\RST\Parser;
use Doctrine\RST\Directives\Directive;

class ExampleDirective extends Directive
{
    public function getName() : string
    {
        return 'example';
    }

    /**
     * @param string[] $options
     */
    public function process(
        Parser $parser,
        ?Node $node,
        string $variable,
        string $data,
        array $options
    ) : void {
        // do something to $node
    }
}

Now you can register your directive by passing it to the 2nd argument of the Doctrine\RST\Kernel class:

use App\RST\Directives\ExampleDirective;

$kernel = new Kernel($configuration, [
    new ExampleDirective()
]);

$builder = new Builder($kernel);

SubDirective Class

You can also extend the Doctrine\RST\Directives\SubDirective class and implement the processSub() method if you want the sub block to be parsed. Here is an example CautionDirective:

namespace App\RST\Directives;

use Doctrine\RST\Nodes\Node;
use Doctrine\RST\Nodes\WrapperNode;
use Doctrine\RST\Parser;
use Doctrine\RST\Directives\SubDirective;

class CautionDirective extends SubDirective
{
    public function getName() : string
    {
        return 'caution';
    }

    /**
     * @param string[] $options
     */
    public function processSub(
        Parser $parser,
        ?Node $document,
        string $variable,
        string $data,
        array $options
    ) : ?Node {
        $divOpen = $parser->renderTemplate('div-open.html.twig', [
            'class' => 'caution',
        ]);

        return $parser->getNodeFactory()->createWrapperNode($document, $divOpen, '</div>');
    }
}

Now you can use the directive like this and it can contain other reStructuredText syntaxes:

.. caution::

    This is some **bold** text!

The above example would output the following HTML:

<div class="caution"><p>This is some <strong>bold</strong> text!</p></div>

</html>

3.1 KiB Raw Blame History

Custom Directives

Directive Class

Example Directive

SubDirective Class

3.1 KiB

Raw Blame History