[FEATURE] Introduce NavigationTitle

packages/guides-restructured-text/resources/config/guides-restructured-text.php

@@ -81,6 +81,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\DateFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\DedicationFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\FieldListItemRule;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NavigationTitleFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NocommentsFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NosearchFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\OrganizationFieldListItemRule;
@@ -320,6 +321,9 @@
         ->set(DedicationFieldListItemRule::class)
         ->tag('phpdoc.guides.parser.rst.fieldlist')
 
+        ->set(NavigationTitleFieldListItemRule::class)
+        ->tag('phpdoc.guides.parser.rst.fieldlist')
+
         ->set(NocommentsFieldListItemRule::class)
         ->tag('phpdoc.guides.parser.rst.fieldlist')
 

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

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList;
+
+use phpDocumentor\Guides\Nodes\FieldLists\FieldListItemNode;
+use phpDocumentor\Guides\Nodes\Metadata\MetadataNode;
+use phpDocumentor\Guides\Nodes\Metadata\NavigationTitleNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+
+use function strtolower;
+
+final class NavigationTitleFieldListItemRule implements FieldListItemRule
+{
+    public function applies(FieldListItemNode $fieldListItemNode): bool
+    {
+        return strtolower($fieldListItemNode->getTerm()) === 'navigation-title';
+    }
+
+    public function apply(FieldListItemNode $fieldListItemNode, BlockContext $blockContext): MetadataNode
+    {
+        return new NavigationTitleNode($fieldListItemNode->getPlaintextContent());
+    }
+}

packages/guides/src/Compiler/NodeTransformers/DocumentEntryRegistrationTransformer.php

@@ -15,17 +15,23 @@
 
 use phpDocumentor\Guides\Compiler\CompilerContextInterface;
 use phpDocumentor\Guides\Compiler\NodeTransformer;
+use phpDocumentor\Guides\Event\ModifyDocumentEntryAdditionalData;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\TitleNode;
+use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
 
+use function assert;
+use function is_string;
+
 /** @implements NodeTransformer<Node> */
 final class DocumentEntryRegistrationTransformer implements NodeTransformer
 {
     public function __construct(
         private readonly LoggerInterface $logger,
+        private readonly EventDispatcherInterface|null $eventDispatcher = null,
     ) {
     }
 
@@ -44,7 +50,23 @@ public function leaveNode(Node $node, CompilerContextInterface $compilerContext)
             $this->logger->warning('Document has no title', $compilerContext->getLoggerInformation());
         }
 
-        $entry = new DocumentEntryNode($node->getFilePath(), $node->getTitle() ?? TitleNode::emptyNode(), $node->isRoot());
+        $additionalData = [];
+        if (is_string($node->getNavigationTitle())) {
+            $additionalData['navigationTitle'] = TitleNode::fromString($node->getNavigationTitle());
+        }
+
+        if ($this->eventDispatcher !== null) {
+            $event = $this->eventDispatcher->dispatch(new ModifyDocumentEntryAdditionalData($additionalData, $node, $compilerContext));
+            assert($event instanceof ModifyDocumentEntryAdditionalData);
+            $additionalData = $event->getAdditionalData();
+        }
+
+        $entry = new DocumentEntryNode(
+            $node->getFilePath(),
+            $node->getTitle() ?? TitleNode::emptyNode(),
+            $node->isRoot(),
+            $additionalData,
+        );
         $compilerContext->getProjectNode()->addDocumentEntry($entry);
 
         return $node->setDocumentEntry($entry);

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/GlobMenuEntryNodeTransformer.php

@@ -20,6 +20,7 @@
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
 
 use function array_pop;
 use function assert;
@@ -65,10 +66,16 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
                 }
             }
 
+            $titleNode = $documentEntry->getTitle();
+            $navigationTitle =  $documentEntry->getAdditionalData('navigationTitle');
+            if ($navigationTitle instanceof TitleNode) {
+                $titleNode = $navigationTitle;
+            }
+
             $documentEntriesInTree[] = $documentEntry;
             $newEntryNode = new InternalMenuEntryNode(
                 $documentEntry->getFile(),
-                $documentEntry->getTitle(),
+                $titleNode,
                 [],
                 false,
                 1,

packages/guides/src/Compiler/NodeTransformers/MenuNodeTransformers/InternalMenuEntryNodeTransformer.php

@@ -19,6 +19,7 @@
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use Psr\Log\LoggerInterface;
 
@@ -63,10 +64,20 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
                 continue;
             }
 
+            $titleNode = $documentEntry->getTitle();
+            $navigationTitle =  $documentEntry->getAdditionalData('navigationTitle');
+            if ($navigationTitle instanceof TitleNode) {
+                $titleNode = $navigationTitle;
+            }
+
+            if ($entryNode->getValue() instanceof TitleNode) {
+                $titleNode = $entryNode->getValue();
+            }
+
             $documentEntriesInTree[] = $documentEntry;
             $newEntryNode = new InternalMenuEntryNode(
                 $documentEntry->getFile(),
-                $entryNode->getValue() ?? $documentEntry->getTitle(),
+                $titleNode,
                 [],
                 false,
                 1,

packages/guides/src/Event/ModifyDocumentEntryAdditionalData.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Event;
+
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Nodes\Node;
+
+final class ModifyDocumentEntryAdditionalData
+{
+    /** @param array<string, Node> $additionalData */
+    public function __construct(
+        private array $additionalData,
+        private readonly DocumentNode $documentNode,
+        private readonly CompilerContextInterface $compilerContext,
+    ) {
+    }
+
+    /** @return array<string, Node> */
+    public function getAdditionalData(): array
+    {
+        return $this->additionalData;
+    }
+
+    /** @param array<string, Node> $additionalData */
+    public function setAdditionalData(array $additionalData): ModifyDocumentEntryAdditionalData
+    {
+        $this->additionalData = $additionalData;
+
+        return $this;
+    }
+
+    public function getDocumentNode(): DocumentNode
+    {
+        return $this->documentNode;
+    }
+
+    public function getCompilerContext(): CompilerContextInterface
+    {
+        return $this->compilerContext;
+    }
+}

packages/guides/src/NodeRenderers/Html/BreadCrumbNodeRenderer.php

@@ -19,6 +19,7 @@
 use phpDocumentor\Guides\Nodes\Menu\InternalMenuEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\MenuEntryNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\RenderContext;
 use phpDocumentor\Guides\TemplateRenderer;
 
@@ -107,9 +108,15 @@ private function buildBreadcrumb(
         int $level,
         bool $isCurrent,
     ): array {
+        $title = $documentEntry->getTitle();
+        $navigationTitle =  $documentEntry->getAdditionalData('navigationTitle');
+        if ($navigationTitle instanceof TitleNode) {
+            $title = $navigationTitle;
+        }
+
         $entry = new InternalMenuEntryNode(
             $documentEntry->getFile(),
-            $documentEntry->getTitle(),
+            $title,
             [],
             false,
             $level,

packages/guides/src/Nodes/DocumentNode.php

@@ -19,6 +19,7 @@
 use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Metadata\MetadataNode;
+use phpDocumentor\Guides\Nodes\Metadata\NavigationTitleNode;
 
 use function array_filter;
 use function max;
@@ -52,6 +53,8 @@ final class DocumentNode extends CompoundNode
     private int $maxFootnoteNumber = 0;
     private int $lastReturnedAnonymousFootnoteNumber = -1;
 
+    private string|null $navigationTitle = null;
+
     /**
      * Variables are replacements in a document or project.
      *
@@ -97,6 +100,11 @@ public function getNodes(string $nodeType = Node::class): array
         return array_filter($this->value, static fn ($node): bool => $node instanceof $nodeType);
     }
 
+    public function getNavigationTitle(): string|null
+    {
+        return $this->navigationTitle;
+    }
+
     public function getPageTitle(): string|null
     {
         if ($this->metaTitle !== null) {
@@ -132,6 +140,10 @@ public function setMetaTitle(string $metaTitle): void
 
     public function addHeaderNode(MetadataNode $node): void
     {
+        if ($node instanceof NavigationTitleNode) {
+            $this->navigationTitle = $node->getValue();
+        }
+
         $this->headerNodes[] = $node;
     }
 

packages/guides/src/Nodes/DocumentTree/DocumentEntryNode.php

@@ -13,6 +13,7 @@
 
 namespace phpDocumentor\Guides\Nodes\DocumentTree;
 
+use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\Nodes\TitleNode;
 
@@ -27,10 +28,12 @@ final class DocumentEntryNode extends EntryNode
     /** @var SectionEntryNode[]  */
     private array $sections = [];
 
+    /** @param array<string, Node> $additionalData */
     public function __construct(
         private readonly string $file,
         private readonly TitleNode $titleNode,
         private readonly bool $isRoot = false,
+        private array $additionalData = [],
     ) {
     }
 
@@ -100,4 +103,14 @@ public function findSectionEntry(SectionNode $sectionNode): SectionEntryNode|nul
 
         return null;
     }
+
+    public function getAdditionalData(string $key): Node|null
+    {
+        return $this->additionalData[$key] ?? null;
+    }
+
+    public function addAdditionalData(string $key, Node $value): void
+    {
+        $this->additionalData[$key] = $value;
+    }
 }

packages/guides/src/Nodes/Metadata/NavigationTitleNode.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Nodes\Metadata;
+
+/**
+ * The organization element contains the name of document author's organization,
+ * or the organization responsible for the document.
+ */
+final class NavigationTitleNode extends MetadataNode
+{
+    public function __construct(string $plaintext)
+    {
+        parent::__construct($plaintext);
+    }
+}