Adding icons on menu

docs/how-to-add-docs-contexts.md → docs/adding-docs-contexts.md

@@ -1,4 +1,4 @@
-# How to add docs contexts
+# Adding docs contexts
 
 You can add several contexts of the documentation.
 

docs/how-to-use.md → docs/basic-usage.md

@@ -1,4 +1,4 @@
-# How to use
+# Basic usage
 
 Markdown templates are on `docs` directory.
 

docs/customizing-menu.md

@@ -0,0 +1,76 @@
+# Customizing menu
+
+## Customizing positions of your pages
+
+You can customize pages into a directory. Add a `pages.php` in this directory and just return a list of files.
+This will apply the position you choose in that file.
+
+### Example on the main directory
+```php
+<?php
+// docs/pages.php
+
+return [
+    'my-first-page.md',
+    'my-second-page.md',
+];
+```
+
+### Example on a subdirectory
+```php
+<?php
+// docs/bar/pages.php
+
+return [
+    'my-first-subdirectory-page.md',
+    'my-second-subdirectory-page.md',
+];
+```
+
+### Note
+When a page is not on your custom list, it is placed after those on your `pages.php`.
+
+## Adding icons
+
+You can customize icons on the menu with the same `pages.php` you use to sort your pages into a directory.
+Just add the attributes to set your icon
+
+### Example
+```php
+<?php
+// docs/pages.php
+
+return [
+    'chart.md' => [
+        'icon' => ['data-feather' => 'bar-chart']
+    ],
+];
+```
+
+Then the following template will be added to your menu.
+
+```html
+<span data-feather="bar-chart"></span>
+```
+
+By default, [Feather icons](https://feathericons.com/) is added to the layout.
+But you can also use the icons you want.
+See the [Customizing templates](customizing-templates.md) to add stylesheets and scripts for your icon package.
+
+### Example with Font-awesome
+```php
+<?php
+// docs/pages.php
+
+return [
+    'cookbook.md' => [
+        'icon' => ['class' => 'fas fa-book']
+    ],
+];
+```
+
+Then the following template will be added to your menu.
+
+```html
+<span class="fas fa-book"></span>
+```

docs/customizing-templates.md

@@ -0,0 +1,20 @@
+# Customizing templates
+
+```html
+<!-- templates/bundles/MobizelMarkdownDocsBundle/base.html.twig -->
+{% extends '@!MobizelMarkdownDocs/base.html.twig' %}
+
+{% block title %}
+    Custom title - {{ parent() }}
+{% endblock %}
+
+{% block stylesheets %}
+    {{ parent() }}
+    <link rel="stylesheet" href="path/to/your/custom/css/file"/>
+{% endblock %}
+
+{% block javascripts %}
+    {{ parent() }}
+    <script src="path/to/your/custom/js/file"></script>
+{% endblock %}
+```

docs/how-to-draw-charts.md → docs/drawing-charts.md

@@ -1,4 +1,4 @@
-# How to draw charts
+# Drawing charts
 
 You can draw charts using [Mermaid.js](https://mermaid-js.github.io/)
 

docs/index.md

@@ -1,8 +1,15 @@
 # Documentation
 
+## Getting started
 * [Setup](setup.md)
-* [How to use](how-to-use.md)
-* [How to add docs contexts](how-to-add-docs-contexts.md)
-* [How to add warning and notes](how-to-add-warning-and-notes.md)
-* [How to draw charts](how-to-draw-charts.md)
-* [How to localize your documentation](how-to-localize-your-documentation.md)
+* [Basic usage](basic-usage.md)
+* [Warning and notes](warning-and-notes.md)
+* [Drawing charts](drawing-charts.md)
+
+## Configuration
+* [Adding docs contexts](adding-docs-contexts.md)
+* [Localizing your documentation](localizing-your-documentation.md)
+
+## Customization
+* [Customizing templates](customizing-templates.md)
+* [Customizing menu](customizing-menu.md)

docs/how-to-localize-your-documentation.md → docs/localizing-your-documentation.md

@@ -1,4 +1,4 @@
-# How to localize your documentation
+# Localizing your documentation
 
 You can configure your docs context for localization.
 

docs/how-to-add-warning-and-notes.md → docs/warning-and-notes.md

@@ -1,4 +1,4 @@
-# How to add warning and notes
+# Warning and notes
 
 ## Warning
 ```html

spec/DataProvider/PageCollectionDataProviderSpec.php

@@ -81,8 +81,8 @@ function it_returns_pages_map(
             'cookbook' => 'Cookbook',
             'cookbook/bdd' => 'BDD - Behaviour-driven development',
             'cookbook/bdd/phpspec' => 'Phpspec',
-            'empty' => 'Empty',
             'foo' => 'Foo fighters',
+            'empty' => 'Empty',
             'products' => 'Products',
             'products/books' => 'Book homepage',
             'products/books/nicolas-beuglet' => 'Nicolas Beuglet',
@@ -108,36 +108,45 @@ function it_returns_pages_as_tree(
         $tree['index']->shouldReturn([
             'slug' => 'index',
             'title' => 'Documentation',
+            'metadata' => [],
             'children' => [],
         ]);
 
         $tree['products']->shouldReturn([
             'slug' => 'products',
             'title' => 'Products',
+            'metadata' => [
+                'icon' => ['data-feather' => 'box'],
+            ],
             'children' => [
                 'products/books' => [
                     'slug' => 'products/books',
                     'title' => 'Book homepage',
+                    'metadata' => [],
                     'children' => [
                         'products/books/nicolas-beuglet' => [
                             'slug' => 'products/books/nicolas-beuglet',
                             'title' => 'Nicolas Beuglet',
+                            'metadata' => [],
                             'children' => [],
                         ],
                         'products/books/stephen-king' => [
                             'slug' => 'products/books/stephen-king',
                             'title' => 'Stephen King Books',
+                            'metadata' => [],
                             'children' => [],
                         ],
                     ],
                 ],
                 'products/board-games' => [
                     'slug' => 'products/board-games',
                     'title' => 'Boardgames',
+                    'metadata' => [],
                     'children' => [
                         'products/board-games/puerto-rico' => [
                             'slug' => 'products/board-games/puerto-rico',
                             'title' => 'Puerto-rico',
+                            'metadata' => [],
                             'children' => [],
                         ],
                     ],

src/DataProvider/PageCollectionDataProvider.php

@@ -35,6 +35,7 @@ public function getRootPages(): iterable
     {
         $docsDir = $this->getDocsDir();
         $finder = new Finder();
+        $pagesCustomData = $this->getPagesCustomData($docsDir);
 
         $finder
             ->files()
@@ -43,11 +44,12 @@ public function getRootPages(): iterable
             //->notName('index.md')
             ->depth(0)
             ->append($this->createDirectoryIndexFinder($docsDir))
-            ->sort(PageSorter::sort($this->getPageSorterContents($docsDir)));
+            ->sort(PageSorter::sort($this->getPagesCustomData($docsDir)));
 
         $pages = [];
 
         foreach ($finder as $file) {
+            $customData = $pagesCustomData[$file->getRelativePathname()] ?? [];
             $pageInfo = new PageInfo($file->getPathname(), $file->getRelativePath(), $file->getRelativePathname());
 
             /** @var string $slug */
@@ -57,7 +59,8 @@ public function getRootPages(): iterable
             $pages[] = $this->createPage(
                 (string) $slug,
                 $pageInfo->getTitle(),
-                $pageInfo->getContentWithoutTitle()
+                $pageInfo->getContentWithoutTitle(),
+                $customData ?? []
             );
         }
 
@@ -68,6 +71,7 @@ public function getChildrenPages(string $parentSlug): iterable
     {
         $docsDir = $this->getDocsDir();
         $finder = new Finder();
+        $pagesCustomData = $this->getPagesCustomData($docsDir.'/'.$parentSlug);
 
         try {
             $finder
@@ -77,14 +81,15 @@ public function getChildrenPages(string $parentSlug): iterable
                 ->notName('index.md')
                 ->depth(0)
                 ->append($this->createDirectoryIndexFinder($docsDir.'/'.$parentSlug))
-                ->sort(PageSorter::sort($this->getPageSorterContents($docsDir.'/'.$parentSlug)));
+                ->sort(PageSorter::sort($this->getPagesCustomData($docsDir.'/'.$parentSlug)));
         } catch (DirectoryNotFoundException $exception) {
             return [];
         }
 
         $pages = [];
 
         foreach ($finder as $file) {
+            $customData = $pagesCustomData[$file->getRelativePathname()] ?? [];
             $pageInfo = new PageInfo($file->getPathname(), $file->getRelativePath(), $file->getRelativePathname());
 
             $slug = $parentSlug.'/'.preg_replace('/\.md$/', '', $file->getRelativePathName());
@@ -93,7 +98,8 @@ public function getChildrenPages(string $parentSlug): iterable
             $pages[] = $this->createPage(
                 (string) $slug,
                 $pageInfo->getTitle(),
-                $pageInfo->getContentWithoutTitle()
+                $pageInfo->getContentWithoutTitle(),
+                $customData ?? []
             );
         }
 
@@ -126,6 +132,7 @@ public function getPagesAsTree(): array
             $tree[$page->slug] = [
                 'slug' => $page->slug,
                 'title' => $page->title,
+                'metadata' => $page->metadata,
                 'children' => $this->addChildrenOnTreeNode($page->slug),
             ];
         }
@@ -141,16 +148,17 @@ private function addChildrenOnTreeNode(string $parentSlug): array
             $children[$page->slug] = [
                 'slug' => $page->slug,
                 'title' => $page->title,
+                'metadata' => $page->metadata,
                 'children' => $this->addChildrenOnTreeNode($page->slug),
             ];
         }
 
         return $children;
     }
 
-    private function createPage(string $slug, string $title, string $content): PageOutput
+    private function createPage(string $slug, string $title, string $content, array $metadata = []): PageOutput
     {
-        return new PageOutput($slug, $title, $content);
+        return new PageOutput($slug, $title, $content, null, $metadata);
     }
 
     private function getRootPagesMap(): array
@@ -165,7 +173,7 @@ private function getRootPagesMap(): array
             ->in($docsDir)
             ->depth(0)
             ->append($this->createDirectoryIndexFinder($docsDir))
-            ->sort(PageSorter::sort($this->getPageSorterContents($docsDir)))
+            ->sort(PageSorter::sort($this->getPagesCustomData($docsDir)))
         ;
 
         $pages = [];
@@ -197,7 +205,7 @@ private function getChildrenPagesMap(array $row, array $pages, int &$currentPosi
                 ->notName('index.md')
                 ->depth(0)
                 ->append($this->createDirectoryIndexFinder($docsDir.'/'.$parentSlug))
-                ->sort(PageSorter::sort($this->getPageSorterContents($docsDir.'/'.$parentSlug)))
+                ->sort(PageSorter::sort($this->getPagesCustomData($docsDir.'/'.$parentSlug)))
             ;
         } catch (DirectoryNotFoundException $exception) {
             return $pages;
@@ -238,7 +246,7 @@ private function createDirectoryIndexFinder(string $dir): Finder
             ->depth(1);
     }
 
-    private function getPageSorterContents(string $dir): array
+    private function getPagesCustomData(string $dir): array
     {
         $pageSorterFile = $dir.'/pages.php';
 

src/Dto/PageOutput.php

@@ -19,16 +19,19 @@ final class PageOutput
     public string $title;
     public string $content;
     public ?string $tableOfContents = null;
+    public array $metadata;
 
     public function __construct(
         string $slug,
         string $title,
         string $content,
-        ?string $tableOfContents = null
+        ?string $tableOfContents = null,
+        array $metadata = []
     ) {
         $this->slug = $slug;
         $this->title = $title;
         $this->content = $content;
         $this->tableOfContents = $tableOfContents;
+        $this->metadata = $metadata;
     }
 }