Merge branch 'main' into feature/improve-output-handling

packages/guides-cli/.gitattributes

@@ -2,3 +2,4 @@
 /docs export-ignore
 /tests export-ignore
 /.gitignore export-ignore
+.github export-ignore

packages/guides-cli/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-code/.gitattributes

@@ -0,0 +1,5 @@
+/.gitattributes export-ignore
+/docs export-ignore
+/tests export-ignore
+/.gitignore export-ignore
+.github export-ignore

packages/guides-code/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-graphs/.gitattributes

@@ -2,3 +2,4 @@
 /docs export-ignore
 /tests export-ignore
 /.gitignore export-ignore
+.github export-ignore

packages/guides-graphs/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-markdown/.gitattributes

@@ -2,3 +2,4 @@
 /docs export-ignore
 /tests export-ignore
 /.gitignore export-ignore
+.github export-ignore

packages/guides-markdown/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-markdown/resources/config/guides-markdown.php

@@ -6,6 +6,7 @@
 use phpDocumentor\Guides\Markdown\Parsers\BlockQuoteParser;
 use phpDocumentor\Guides\Markdown\Parsers\CodeBlockParser;
 use phpDocumentor\Guides\Markdown\Parsers\HeaderParser;
+use phpDocumentor\Guides\Markdown\Parsers\HtmlParser;
 use phpDocumentor\Guides\Markdown\Parsers\InlineParsers\EmphasisParser;
 use phpDocumentor\Guides\Markdown\Parsers\InlineParsers\InlineCodeParser;
 use phpDocumentor\Guides\Markdown\Parsers\InlineParsers\InlineImageParser;
@@ -36,6 +37,9 @@
         ->arg('$subParsers', tagged_iterator('phpdoc.guides.markdown.parser.subParser'))
         ->tag('phpdoc.guides.markdown.parser.blockParser')
         ->tag('phpdoc.guides.markdown.parser.subParser')
+        ->set(HtmlParser::class)
+        ->tag('phpdoc.guides.markdown.parser.blockParser')
+        ->tag('phpdoc.guides.markdown.parser.subParser')
         ->set(ListBlockParser::class)
         ->tag('phpdoc.guides.markdown.parser.blockParser')
         ->tag('phpdoc.guides.markdown.parser.subParser')

packages/guides-markdown/src/Markdown/Parsers/HtmlParser.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Markdown\Parsers;
+
+use League\CommonMark\Extension\CommonMark\Node\Block\HtmlBlock;
+use League\CommonMark\Node\Node as CommonMarkNode;
+use League\CommonMark\Node\NodeWalker;
+use League\CommonMark\Node\NodeWalkerEvent;
+use phpDocumentor\Guides\MarkupLanguageParser;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\ParagraphNode;
+use Psr\Log\LoggerInterface;
+
+use function assert;
+
+/** @extends AbstractBlockParser<ParagraphNode> */
+final class HtmlParser extends AbstractBlockParser
+{
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMarkNode $current): ParagraphNode
+    {
+        assert($current instanceof HtmlBlock);
+
+        $this->logger->warning('We do not support plain HTML for security reasons. Escaping all HTML ');
+
+        $walker->next();
+
+        return new ParagraphNode([new InlineCompoundNode([new PlainTextInlineNode($current->getLiteral())])]);
+    }
+
+    public function supports(NodeWalkerEvent $event): bool
+    {
+        return $event->isEntering() && $event->getNode() instanceof HtmlBlock;
+    }
+}

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

@@ -35,6 +35,11 @@ public function parse(MarkupLanguageParser $parser, NodeWalker $walker, CommonMa
     {
         $content = [];
 
+        if ($current->firstChild() === null) {
+            // Handle inline nodes without content
+            return $this->createInlineNode($current, null);
+        }
+
         while ($event = $walker->next()) {
             $commonMarkNode = $event->getNode();
 

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

@@ -11,14 +11,15 @@
 use Psr\Log\LoggerInterface;
 
 use function assert;
+use function sprintf;
 
 /** @extends AbstractInlineTextDecoratorParser<ImageInlineNode> */
 final class InlineImageParser extends AbstractInlineTextDecoratorParser
 {
     /** @param iterable<AbstractInlineParser<InlineNode>> $inlineParsers */
     public function __construct(
         iterable $inlineParsers,
-        LoggerInterface $logger,
+        private readonly LoggerInterface $logger,
     ) {
         parent::__construct($inlineParsers, $logger);
     }
@@ -32,6 +33,16 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
     {
         assert($commonMarkNode instanceof Image);
 
+        if ($content === null) {
+            $this->logger->warning(
+                sprintf(
+                    'Image %s does not have an alternative text. Add an alternative text like this: ![Image description](%s)',
+                    $commonMarkNode->getUrl(),
+                    $commonMarkNode->getUrl(),
+                ),
+            );
+        }
+
         return new ImageInlineNode($commonMarkNode->getUrl(), $content ?? '');
     }
 

packages/guides-restructured-text/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-theme-bootstrap/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides/.gitattributes

@@ -1,5 +1,5 @@
 /.gitattributes export-ignore
 /docs export-ignore
-/examples export-ignore
 /tests export-ignore
 /.gitignore export-ignore
+.github export-ignore

packages/guides/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+# Contribute to the phpDocumentor Guides
+
+## Go to the mono-repository
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+## Create Issues
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+# Make changes (create pull requests)
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

tests/Integration/tests/markdown/html-inline-md/expected/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Markdown with html - Project Title</title>
+
+</head>
+<body>
+    <h1>Markdown with html</h1>
+
+<p>In files of text, where words take flight,Markdown weaves its magic, bold and bright.Hashes and stars, a simple code,A poet&#039;s playground, where stories unfold. &lt;BR&gt;</p>
+</body>
+</html>

tests/Integration/tests/markdown/html-inline-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+>
+    <project title="Project Title" version="6.4"/>
+</guides>

tests/Integration/tests/markdown/html-inline-md/input/index.md

@@ -0,0 +1,6 @@
+# Markdown with html
+
+In files of text, where words take flight,<br/>
+Markdown weaves its magic, bold and bright.<br>
+Hashes and stars, a simple code,<br >
+A poet's playground, where stories unfold. <BR>

tests/Integration/tests/markdown/html-md/expected/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Markdown with html - Project Title</title>
+
+</head>
+<body>
+    <h1>Markdown with html</h1>
+
+<p>&lt;div align=&quot;center&quot;&gt;
+In files of text, where words take flight,
+Markdown weaves its magic, bold and bright.
+Hashes and stars, a simple code,
+A poet&#039;s playground, where stories unfold.
+&lt;/div&gt;</p>
+</body>
+</html>

tests/Integration/tests/markdown/html-md/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: We do not support plain HTML for security reasons. Escaping all HTML

tests/Integration/tests/markdown/html-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+>
+    <project title="Project Title" version="6.4"/>
+</guides>

tests/Integration/tests/markdown/html-md/input/index.md

@@ -0,0 +1,8 @@
+# Markdown with html
+
+<div align="center">
+In files of text, where words take flight,
+Markdown weaves its magic, bold and bright.
+Hashes and stars, a simple code,
+A poet's playground, where stories unfold.
+</div>

tests/Integration/tests/markdown/image-empty-alt-md/expected/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Images with and without alt text - Project Title</title>
+
+</head>
+<body>
+    <h1>Images with and without alt text</h1>
+
+<p><img src="https://example.org/example.png" alt="with alt Text"/></p>
+<p><img src="https://example.org/example2.png" alt=""/></p>
+</body>
+</html>

tests/Integration/tests/markdown/image-empty-alt-md/expected/logs/warning.log

@@ -0,0 +1 @@
+app.WARNING: Image https://example.org/example2.png does not have an alternative text. Add an alternative text like this: ![Image description](https://example.org/example2.png)

tests/Integration/tests/markdown/image-empty-alt-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+>
+    <project title="Project Title" version="6.4"/>
+</guides>

tests/Integration/tests/markdown/image-empty-alt-md/input/index.md

@@ -0,0 +1,5 @@
+# Images with and without alt text
+
+![with alt Text](https://example.org/example.png)
+
+![](https://example.org/example2.png)

tests/Integration/tests/markdown/linked-image-md/expected/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Markdown with linked images - Project Title</title>
+
+</head>
+<body>
+    <h1>Markdown with linked images</h1>
+
+<p><a href="https://github.com/AOEpeople/TYPO3-Feature-Flag/actions"><img src="https://github.com/AOEpeople/TYPO3-Feature-Flag/actions"/></a><a href="https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main"><img src="https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main"/></a><a href="https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main"><img src="https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main"/></a></p>
+</body>
+</html>

tests/Integration/tests/markdown/linked-image-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+>
+    <project title="Project Title" version="6.4"/>
+</guides>

tests/Integration/tests/markdown/linked-image-md/input/index.md

@@ -0,0 +1,5 @@
+# Markdown with linked images
+
+[![Build Status](https://github.com/AOEpeople/TYPO3-Feature-Flag/workflows/CI/badge.svg?branch=main)](https://github.com/AOEpeople/TYPO3-Feature-Flag/actions)
+[![Code Coverage](https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/badges/coverage.png?b=main)](https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main)
+[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/AOEpeople/TYPO3-Feature-Flag/?branch=main)

tests/Integration/tests/markdown/linked-image-md/input/skip

@@ -0,0 +1 @@
+Linked images are currently not supported