Markdown supports more nesting on nodes than RST does.

To support this we needed to add support for compound nodes.
We tried to be backward compatible for people building their own template.
This layer will be removed in v2 and therfor we do trigger deprecations. See #1161

Fixes: #1160

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/AbstractInlineParser.php

@@ -17,13 +17,13 @@
 use League\CommonMark\Node\NodeWalker;
 use phpDocumentor\Guides\Markdown\ParserInterface;
 use phpDocumentor\Guides\MarkupLanguageParser;
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 
 /**
- * @template TValue as InlineNode
+ * @template TValue as InlineNodeInterface
  * @implements ParserInterface<TValue>
  */
 abstract class AbstractInlineParser implements ParserInterface
 {
-    abstract public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode;
+    abstract public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface;
 }

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/AbstractInlineTextDecoratorParser.php

@@ -18,16 +18,16 @@
 use League\CommonMark\Node\NodeWalkerEvent;
 use phpDocumentor\Guides\MarkupLanguageParser;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use Psr\Log\LoggerInterface;
 use RuntimeException;
 
 use function count;
 use function sprintf;
-use function var_export;
 
 /**
- * @template TValue as InlineNode
+ * @template TValue as InlineNodeInterface
  * @extends AbstractInlineParser<TValue>
  */
 abstract class AbstractInlineTextDecoratorParser extends AbstractInlineParser
@@ -40,7 +40,7 @@ public function __construct(
     }
 
     /** @return TValue */
-    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode
+    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
     {
         $content = [];
 
@@ -66,12 +66,10 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa
 
             if ($this->supportsCommonMarkNode($commonMarkNode)) {
                 if (count($content) === 1 && $content[0] instanceof PlainTextInlineNode) {
-                    return $this->createInlineNode($commonMarkNode, $content[0]->getValue());
+                    return $this->createInlineNode($commonMarkNode, $content[0]->getValue(), $content);
                 }
 
-                $this->logger->warning(sprintf('%s CONTEXT: Content of emphasis could not be interpreted: %s', $this->getType(), var_export($content, true)));
-
-                return $this->createInlineNode($commonMarkNode, null);
+                return $this->createInlineNode($commonMarkNode, null, $content);
             }
 
             $this->logger->warning(sprintf('%s context does not allow a %s node', $this->getType(), $commonMarkNode::class));
@@ -83,7 +81,7 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa
     abstract protected function getType(): string;
 
     /** @return TValue */
-    abstract protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode;
+    abstract protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNodeInterface;
 
     abstract protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool;
 

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/EmphasisParser.php

@@ -17,6 +17,7 @@
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use Psr\Log\LoggerInterface;
 
 /** @extends AbstractInlineTextDecoratorParser<EmphasisInlineNode> */
@@ -35,9 +36,10 @@ protected function getType(): string
         return 'Emphasis';
     }
 
-    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
+    /** @param InlineNodeInterface[] $children */
+    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new EmphasisInlineNode($content ?? '');
+        return new EmphasisInlineNode($content ?? '', $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/InlineCodeParser.php

@@ -18,14 +18,15 @@
 use League\CommonMark\Node\NodeWalker;
 use League\CommonMark\Node\NodeWalkerEvent;
 use phpDocumentor\Guides\MarkupLanguageParser;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
 
 use function assert;
 
 /** @extends AbstractInlineParser<LiteralInlineNode> */
 final class InlineCodeParser extends AbstractInlineParser
 {
-    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): LiteralInlineNode
+    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
     {
         assert($current instanceof Code);
 

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/InlineImageParser.php

@@ -17,6 +17,7 @@
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\ImageInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use Psr\Log\LoggerInterface;
 
 use function assert;
@@ -38,7 +39,7 @@ protected function getType(): string
         return 'Image';
     }
 
-    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
+    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNodeInterface
     {
         assert($commonMarkNode instanceof Image);
 

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php

@@ -17,6 +17,7 @@
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use Psr\Log\LoggerInterface;
 
 use function assert;
@@ -42,7 +43,8 @@ protected function getType(): string
         return 'Link';
     }
 
-    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
+    /** @param InlineNodeInterface[] $children */
+    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
         assert($commonMarkNode instanceof Link);
 
@@ -52,7 +54,7 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
             $url = substr($url, 0, -3);
         }
 
-        return new HyperLinkNode($content, $url);
+        return new HyperLinkNode($content, $url, $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/NewLineParser.php

@@ -18,7 +18,7 @@
 use League\CommonMark\Node\NodeWalker;
 use League\CommonMark\Node\NodeWalkerEvent;
 use phpDocumentor\Guides\MarkupLanguageParser;
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 
 /** @extends AbstractInlineParser<PlainTextInlineNode> */
@@ -28,7 +28,7 @@ public function __construct()
     {
     }
 
-    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNode
+    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): InlineNodeInterface
     {
         return new PlainTextInlineNode(' ');
     }

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/StrongParser.php

@@ -16,6 +16,7 @@
 use League\CommonMark\Extension\CommonMark\Node\Inline\Strong;
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use Psr\Log\LoggerInterface;
 
@@ -35,9 +36,10 @@ protected function getType(): string
         return 'StrongDecorator';
     }
 
-    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
+    /** @param InlineNodeInterface[] $children */
+    protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new StrongInlineNode($content ?? '');
+        return new StrongInlineNode($content ?? '', $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/DefaultTextRoleRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -27,7 +27,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::BACKTICK;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $text = '';
 

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/EmphasisRule.php

@@ -14,7 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -28,7 +28,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::EMPHASIS_DELIMITER;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $text = '';
 

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/InlineRule.php

@@ -13,15 +13,15 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
 interface InlineRule
 {
     public function applies(InlineLexer $lexer): bool;
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null;
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null;
 
     public function getPriority(): int;
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/InternalReferenceRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -24,7 +24,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::UNDERSCORE;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $text = '';
         $initialPosition = $lexer->token?->position;

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedPhraseRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 use phpDocumentor\Guides\RestructuredText\Parser\References\EmbeddedReferenceParser;
@@ -37,7 +37,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::BACKTICK;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $value = '';
         $initialPosition = $lexer->token?->position;

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/NamedReferenceRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -35,7 +35,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::NAMED_REFERENCE;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $value = rtrim($lexer->token?->value ?? '', '_');
         $node = $this->createReference($blockContext, $value);

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/StrongRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
@@ -28,7 +28,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::STRONG_DELIMITER;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $text = '';
 

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/TextRoleRule.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -29,7 +29,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::COLON;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNodeInterface|null
     {
         $domain = null;
         $role = null;

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/LineBlockRule.php

@@ -14,7 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions;
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\Nodes\Inline\NewlineInlineNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\RestructuredText\Nodes\ContainerNode;
@@ -71,7 +71,7 @@ private function collectContentLines(BlockContext $blockContext): Buffer
         return $buffer;
     }
 
-    /** @return CompoundNode<InlineNode> */
+    /** @return CompoundNode<InlineNodeInterface> */
     private function createLine(BlockContext $blockContext, Buffer $buffer): CompoundNode
     {
         $line = $this->inlineMarkupRule->apply(new BlockContext(

packages/guides-restructured-text/src/RestructuredText/TextRoles/TextRole.php

@@ -13,7 +13,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
-use phpDocumentor\Guides\Nodes\Inline\InlineNode;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 
 interface TextRole
@@ -32,5 +32,5 @@ public function processNode(
         string $role,
         string $content,
         string $rawContent,
-    ): InlineNode;
+    ): InlineNodeInterface;
 }

packages/guides-theme-rst/resources/template/rst/template.php

@@ -76,7 +76,6 @@
     AnnotationListNode::class => 'body/annotation-list.rst.twig',
     // Inline
     ImageInlineNode::class => 'inline/image.rst.twig',
-    InlineCompoundNode::class => 'inline/inline-node.rst.twig',
     AbbreviationInlineNode::class => 'inline/textroles/abbreviation.rst.twig',
     CitationInlineNode::class => 'inline/citation.rst.twig',
     DocReferenceNode::class => 'inline/doc.rst.twig',
@@ -91,6 +90,7 @@
     StrongInlineNode::class => 'inline/strong.rst.twig',
     VariableInlineNode::class => 'inline/variable.rst.twig',
     GenericTextRoleInlineNode::class => 'inline/textroles/generic.rst.twig',
+    InlineCompoundNode::class => 'inline/inline-node.rst.twig',
     // Output as Metatags
     AuthorNode::class => 'structure/header/author.rst.twig',
     CopyrightNode::class => 'structure/header/copyright.rst.twig',

packages/guides/resources/template/html/inline/emphasis.html.twig

@@ -1 +1,5 @@
-<em>{{- node.value -}}</em>
+<em>
+    {%- for child in node.children -%}
+        {{- renderNode(child) -}}
+    {%- endfor -%}
+</em>