From b1200a199cbb32db288ae0f2c179d12f2a6ebee9 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Fri, 11 Oct 2024 15:31:31 +0200 Subject: [PATCH 1/2] [FEATURE] Support GitHub like Markdown Admonitions See https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts Resolves https://github.com/phpDocumentor/guides/issues/1089 --- .../src/Markdown/Parsers/BlockQuoteParser.php | 63 ++++++++++++++++++- .../AbstractAdmonitionDirective.php | 2 +- .../Directives/AdmonitionDirective.php | 2 +- .../Html/AdmonitionNodeRenderer.php | 2 +- .../template/body/admonition.html.twig | 6 +- .../body/admonitions/caution.html.twig | 4 ++ .../body/admonitions/important.html.twig | 4 +- .../body/admonitions/warning.html.twig | 2 +- .../src}/Nodes/AdmonitionNode.php | 6 +- .../bootstrap-admonition/expected/index.html | 3 +- .../expected/index.html | 14 +++-- .../expected/index.html | 15 ++--- .../expected/index.html | 16 ++--- .../admonitions-md/expected/index.html | 25 ++++++++ .../markdown/admonitions-md/input/guides.xml | 10 +++ .../markdown/admonitions-md/input/index.md | 16 +++++ 16 files changed, 153 insertions(+), 37 deletions(-) create mode 100644 packages/guides-theme-bootstrap/resources/template/body/admonitions/caution.html.twig rename packages/{guides-restructured-text/src/RestructuredText => guides/src}/Nodes/AdmonitionNode.php (83%) create mode 100644 tests/Integration/tests/markdown/admonitions-md/expected/index.html create mode 100644 tests/Integration/tests/markdown/admonitions-md/input/guides.xml create mode 100644 tests/Integration/tests/markdown/admonitions-md/input/index.md diff --git a/packages/guides-markdown/src/Markdown/Parsers/BlockQuoteParser.php b/packages/guides-markdown/src/Markdown/Parsers/BlockQuoteParser.php index 384446595..348524ce3 100644 --- a/packages/guides-markdown/src/Markdown/Parsers/BlockQuoteParser.php +++ b/packages/guides-markdown/src/Markdown/Parsers/BlockQuoteParser.php @@ -18,14 +18,21 @@ use League\CommonMark\Node\NodeWalker; use League\CommonMark\Node\NodeWalkerEvent; use phpDocumentor\Guides\MarkupLanguageParser; +use phpDocumentor\Guides\Nodes\AdmonitionNode; +use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode; +use phpDocumentor\Guides\Nodes\InlineCompoundNode; use phpDocumentor\Guides\Nodes\Node; +use phpDocumentor\Guides\Nodes\ParagraphNode; use phpDocumentor\Guides\Nodes\QuoteNode; use Psr\Log\LoggerInterface; use RuntimeException; +use function array_shift; +use function count; use function sprintf; +use function trim; -/** @extends AbstractBlockParser */ +/** @extends AbstractBlockParser */ final class BlockQuoteParser extends AbstractBlockParser { /** @param iterable> $subParsers */ @@ -35,7 +42,7 @@ public function __construct( ) { } - public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): QuoteNode + public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): Node { $content = []; @@ -55,6 +62,58 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa // leaving the heading node if ($commonMarkNode instanceof BlockQuote) { + if (count($content) > 0 and $content[0] instanceof ParagraphNode and ($content[0]->getValue()[0]) instanceof InlineCompoundNode) { + $paragraphContent = $content[0]->getValue()[0]->getValue(); + if (count($paragraphContent) > 0 and $paragraphContent[0] instanceof PlainTextInlineNode) { + $text = trim($paragraphContent[0]->getValue()); + $newParagraphContent = $paragraphContent; + array_shift($newParagraphContent); + switch ($text) { + case '[!NOTE]': + return new AdmonitionNode( + 'note', + new InlineCompoundNode([new PlainTextInlineNode('Note')]), + 'Note', + $newParagraphContent, + ); + + case '[!TIP]': + return new AdmonitionNode( + 'tip', + new InlineCompoundNode([new PlainTextInlineNode('Tip')]), + 'Tip', + $newParagraphContent, + ); + + case '[!IMPORTANT]': + return new AdmonitionNode( + 'important', + new InlineCompoundNode([new PlainTextInlineNode('Important')]), + 'Important', + $newParagraphContent, + ); + + case '[!WARNING]': + return new AdmonitionNode( + 'warning', + new InlineCompoundNode([new PlainTextInlineNode('Warning')]), + 'Warning', + $newParagraphContent, + ); + + case '[!CAUTION]': + return new AdmonitionNode( + 'caution', + new InlineCompoundNode([new PlainTextInlineNode('Caution')]), + 'Caution', + $newParagraphContent, + ); + } + } + + $content[0] = new ParagraphNode([new InlineCompoundNode($paragraphContent)]); + } + return new QuoteNode($content); } diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php index d4d36d35b..cb5deca86 100644 --- a/packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php +++ b/packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php @@ -13,9 +13,9 @@ namespace phpDocumentor\Guides\RestructuredText\Directives; +use phpDocumentor\Guides\Nodes\AdmonitionNode; use phpDocumentor\Guides\Nodes\CollectionNode; use phpDocumentor\Guides\Nodes\Node; -use phpDocumentor\Guides\RestructuredText\Nodes\AdmonitionNode; use phpDocumentor\Guides\RestructuredText\Parser\BlockContext; use phpDocumentor\Guides\RestructuredText\Parser\Directive; use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule; diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php index 7f3a44a28..300e5557f 100644 --- a/packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php +++ b/packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php @@ -13,9 +13,9 @@ namespace phpDocumentor\Guides\RestructuredText\Directives; +use phpDocumentor\Guides\Nodes\AdmonitionNode; use phpDocumentor\Guides\Nodes\CollectionNode; use phpDocumentor\Guides\Nodes\Node; -use phpDocumentor\Guides\RestructuredText\Nodes\AdmonitionNode; use phpDocumentor\Guides\RestructuredText\Parser\BlockContext; use phpDocumentor\Guides\RestructuredText\Parser\Directive; diff --git a/packages/guides-restructured-text/src/RestructuredText/NodeRenderers/Html/AdmonitionNodeRenderer.php b/packages/guides-restructured-text/src/RestructuredText/NodeRenderers/Html/AdmonitionNodeRenderer.php index b1aa25fee..6d05d3cff 100644 --- a/packages/guides-restructured-text/src/RestructuredText/NodeRenderers/Html/AdmonitionNodeRenderer.php +++ b/packages/guides-restructured-text/src/RestructuredText/NodeRenderers/Html/AdmonitionNodeRenderer.php @@ -15,9 +15,9 @@ use InvalidArgumentException; use phpDocumentor\Guides\NodeRenderers\NodeRenderer; +use phpDocumentor\Guides\Nodes\AdmonitionNode; use phpDocumentor\Guides\Nodes\Node; use phpDocumentor\Guides\RenderContext; -use phpDocumentor\Guides\RestructuredText\Nodes\AdmonitionNode; use phpDocumentor\Guides\TemplateRenderer; use function implode; diff --git a/packages/guides-theme-bootstrap/resources/template/body/admonition.html.twig b/packages/guides-theme-bootstrap/resources/template/body/admonition.html.twig index 2d7ecfcdf..6c1b94fbd 100644 --- a/packages/guides-theme-bootstrap/resources/template/body/admonition.html.twig +++ b/packages/guides-theme-bootstrap/resources/template/body/admonition.html.twig @@ -1,11 +1,13 @@ - +{% if name == 'caution' %} + {% include "body/admonitions/caution.html.twig" %} +{% endif %} {% if name == 'important' %} {% include "body/admonitions/important.html.twig" %} {% endif %} {% if name == 'note' %} {% include "body/admonitions/note.html.twig" %} {% endif %} -{% if name == 'warning' or name == 'caution' %} +{% if name == 'warning' %} {% include "body/admonitions/warning.html.twig" %} {% endif %} {% if name == 'tip' or name == 'hint' %} diff --git a/packages/guides-theme-bootstrap/resources/template/body/admonitions/caution.html.twig b/packages/guides-theme-bootstrap/resources/template/body/admonitions/caution.html.twig new file mode 100644 index 000000000..fe7b30d11 --- /dev/null +++ b/packages/guides-theme-bootstrap/resources/template/body/admonitions/caution.html.twig @@ -0,0 +1,4 @@ + diff --git a/packages/guides-theme-bootstrap/resources/template/body/admonitions/important.html.twig b/packages/guides-theme-bootstrap/resources/template/body/admonitions/important.html.twig index dd0705323..30301fde7 100644 --- a/packages/guides-theme-bootstrap/resources/template/body/admonitions/important.html.twig +++ b/packages/guides-theme-bootstrap/resources/template/body/admonitions/important.html.twig @@ -1,4 +1,4 @@ -