[Site]: add breadcrumbs

site/11ty/collections.filter.js

@@ -7,6 +7,7 @@ const get = (item, path) => path.split('.').reduce((acc, key) => acc && acc[key]
  * - if values are passed, include items that have a value that matches one of the passed values
  */
 function filter(collection, prop, ...values) {
+  values = values.flat(1);
   const matcher = values.length > 0 ?
     (item) => values.includes(get(item, prop)) :
     (item) => !!get(item, prop);
@@ -19,6 +20,7 @@ function filter(collection, prop, ...values) {
  * - if values are passed, exclude items that have a value that matches one of the passed values
  */
 function exclude(collection, prop, ...values) {
+  values = values.flat(1);
   const matcher = values.length > 0 ?
     (item) => !values.includes(get(item, prop)) :
     (item) => !get(item, prop);

site/11ty/markdown.shortcut.js

@@ -16,15 +16,23 @@ class MDRenderer {
       // Exclude part before start anchor
       if (startAnchor) {
         const startAnchorElement = MDRenderer.findAnchor(window.document, startAnchor);
-        while (startAnchorElement.previousSibling) startAnchorElement.previousSibling.remove();
-        startAnchorElement.remove();
+        if (startAnchorElement) {
+          while (startAnchorElement.previousSibling) startAnchorElement.previousSibling.remove();
+          startAnchorElement.remove();
+        } else {
+          console.error('MDRenderer.render: start anchor "%s" not found for %s', startAnchor, filePath);
+        }
       }
 
       // Exclude part after end anchor
       if (endAnchor) {
         const endAnchorElement = MDRenderer.findAnchor(window.document, endAnchor);
-        while (endAnchorElement.nextSibling) endAnchorElement.nextSibling.remove();
-        endAnchorElement.remove();
+        if (endAnchorElement) {
+          while (endAnchorElement.nextSibling) endAnchorElement.nextSibling.remove();
+          endAnchorElement.remove();
+        } else {
+          console.error('MDRenderer.render: end anchor "%s" not found for %s', endAnchor, filePath);
+        }
       }
 
       // Resolve content links
@@ -33,7 +41,8 @@ class MDRenderer {
       // Render result content
       return MDRenderer.renderContent(window.document.body);
     } catch (e) {
-      return `Rendering error: ${e}`;
+      console.error('MDRenderer.render: error during rendering...\n%s', e);
+      return `Critical rendering error: ${e}`;
     }
   }
 

site/11ty/tree.filter.js

@@ -1,8 +1,28 @@
+const findPage = (items, page) => items.find((item) => item.data.page.url === page.url);
+
 const findParent = (list, parent) => {
-  if (!parent) return null;
-  return list.find((item) => item.fileSlug === parent || item.data.id === parent || item.data.title === parent);
+  const alias = parent?.data?.parent;
+  if (!alias) return null;
+  const candidates = list.filter((item) => item.fileSlug === alias || item.data.id === alias || item.data.title === alias);
+  const parentPath = parent.data.page.url.split('/');
+  const similarity = (item) => {
+    const itemPath = item.data.page.url.split('/');
+    let i = 0;
+    while (itemPath[i] === parentPath[i]) i++;
+    return i;
+  };
+  // Sort by file system tree position to ensure the last item is the one we want
+  candidates.sort((a, b) => similarity(a) - similarity(b));
+  return candidates.pop();
 };
 
+function * findParents(items, page) {
+  while (page) {
+    page = findParent(items, page);
+    if (page) yield page;
+  }
+}
+
 /** Group items into a tree structure using given property */
 function treeBuilder(items) {
   const root = [];
@@ -11,7 +31,7 @@ function treeBuilder(items) {
     item.data.index = index;
   });
   items.forEach((item) => {
-    const parent = findParent(items, item.data.parent);
+    const parent = findParent(items, item);
     if (parent) {
       parent.children.push(item);
     } else {
@@ -21,6 +41,13 @@ function treeBuilder(items) {
   return root;
 }
 
+function parents(items) {
+  if (!Array.isArray(items)) return;
+  const currentPage = findPage(items, this.page);
+  return  [...findParents(items, currentPage)].reverse();
+}
+
 module.exports = (config) => {
   config.addFilter('tree', treeBuilder);
+  config.addFilter('parents', parents);
 };

site/src/navigation/breadcrumbs/breadcrumbs.less

@@ -0,0 +1,15 @@
+.page-breadcrumbs {
+  margin-top: 20px;
+  color: @primary-blue;
+
+  .page-breadcrumb {
+    display: inline-block;
+    list-style: none;
+  }
+
+  .page-breadcrumb::after {
+    content: '/';
+    color: #000;
+    margin-inline: 10px;
+  }
+}

site/src/navigation/navigation.less

@@ -6,3 +6,5 @@
 
 @import './footer/footer.less';
 @import './footer/footer-compact.less';
+
+@import './breadcrumbs/breadcrumbs.less';

site/views/_includes/navigation/breadcrumbs.njk

@@ -0,0 +1,9 @@
+<ul class="page-breadcrumbs">
+  {% for item in collections.nav | filter('data.collection', tags) %}
+    <li class="page-breadcrumb"><a href="{{ item.url }}">{{ item.data.title }}</a></li>
+  {% endfor %}
+
+  {% for item in collections.all | parents %}
+    <li class="page-breadcrumb"><a href="{{ item.url }}">{{ item.data.title }}</a></li>
+  {% endfor %}
+</ul>

site/views/_includes/navigation/collection-grid.njk

@@ -25,8 +25,8 @@
           </div>
           <hr class="collection-grid-divider" />
           <div class="collection-grid-box collection-grid-svg">
-            {% if item.data.icon %}
-              {% include "static/assets/" + item.data.icon %}
+            {% if item.data.collectionIcon or item.data.icon %}
+              {% include "static/assets/" + (item.data.collectionIcon or item.data.icon) %}
             {% elseif options.isList %}
               <span class="arrows-icon right"></span>
             {% elseif item.data.iconAlt %}

site/views/_includes/navigation/header.njk

@@ -46,7 +46,7 @@
       </li>
     </ul>
     <div class="header-utility">
-      <a class="header-btn btn btn-lg btn-sec-blue" href="{{ '/introduction' | url }}">Get started</a>
+      <a class="header-btn btn btn-lg btn-sec-blue" href="{{ '/introduction/installation-guide/' | url }}">Get started</a>
       <esl-trigger class="header-hamburger hide-desktop"
                    target="#sidebar"
                    a11y-label-active="Close navigation menu"

site/views/_includes/navigation/sidebar-item.njk

@@ -1,69 +1,71 @@
 {% macro navItem(title, collection, icon, opt = {}) %}
-  {% set isDraftCollection = collection == 'draft' %}
+  {% set isDevCollection = collection == 'dev' %}
   {% set isPrimaryActive = functions.isActivePath(page.url, collection) %}
 
-  {% if isDraftCollection and not env.isDev %}
+  {% if isDevCollection and not env.isDev %}
     {% set items = collections[collection] | filter('url', page.url) | tree %}
   {% else %}
     {% set items = collections[collection] | released | tree %}
   {% endif %}
 
   {% if items.length %}
-  <div class="sidebar-nav-item-heading {{ 'active' if isPrimaryActive }}">
-    <a class="sidebar-nav-item-link icon-link" href="{{ ('/' + collection) | url }}"
-       aria-label="{{ title }} home page">
-      {% include icon %}
-    </a>
-    <esl-trigger class="sidebar-nav-item-trigger sidebar-nav-item-arrow"
-                 target="::parent::next"
-                 a11y-label-active="Collapse {{ title }} section"
-                 a11y-label-inactive="Expand {{ title }} section"
-                 {% if isPrimaryActive %}active{% endif %}>
-      {{ title }}
-      {% if opt.beta %}
-        <sup class="badge badge-sup badge-warning">beta</sup>
-      {% endif %}
-      {% if opt.new %}
-        <sup class="badge badge-sup badge-success">new</sup>
-      {% endif %}
-    </esl-trigger>
-  </div>
+  <li class="sidebar-nav-item">
+    <div class="sidebar-nav-item-heading {{ 'active' if isPrimaryActive }}">
+      <a class="sidebar-nav-item-link icon-link" href="{{ ('/' + collection) | url }}"
+         aria-label="{{ title }} home page">
+        {% include "static/assets/" + icon %}
+      </a>
+      <esl-trigger class="sidebar-nav-item-trigger sidebar-nav-item-arrow"
+                   target="::parent::next"
+                   a11y-label-active="Collapse {{ title }} section"
+                   a11y-label-inactive="Expand {{ title }} section"
+                   {% if isPrimaryActive %}active{% endif %}>
+        {{ title }}
+        {% if opt.beta %}
+          <sup class="badge badge-sup badge-warning">beta</sup>
+        {% endif %}
+        {% if opt.new %}
+          <sup class="badge badge-sup badge-success">new</sup>
+        {% endif %}
+      </esl-trigger>
+    </div>
 
-  <esl-panel id="sidebar-{{ collection }}-menu"
-             class="sidebar-nav-secondary {{ 'open' if isPrimaryActive }}"
-             {% if isPrimaryActive %}data-open{% endif %}
-             group="esl-nav"
-             fallback-duration="400">
-    {{ linkList(items, isDraftCollection) }}
-  </esl-panel>
+    <esl-panel id="sidebar-{{ collection }}-menu"
+               class="sidebar-nav-secondary {{ 'open' if isPrimaryActive }}"
+               {% if isPrimaryActive %}data-open{% endif %}
+               group="esl-nav"
+               fallback-duration="400">
+      {{ linkList(items, isDevCollection) }}
+    </esl-panel>
+  </li>
   {% endif %}
 {% endmacro %}
 
-{% macro linkList(items, isDraftCollection) %}
+{% macro linkList(items, isDevCollection) %}
   <ul class="sidebar-nav-secondary-list">
     <esl-a11y-group targets="::child(li)::find(.sidebar-nav-secondary-link)"></esl-a11y-group>
     {% for item in items | sortBy('order', 'name') %}
       {% if item.children.length %}
-        {{ subnavItem(item, isDraftCollection) }}
+        {{ subnavItem(item, isDevCollection) }}
       {% else %}
-        {{ link(item, isDraftCollection) }}
+        {{ link(item, isDevCollection) }}
       {% endif %}
     {% endfor %}
   </ul>
 {% endmacro %}
 
-{% macro subnavItem(item, isDraftCollection) %}
+{% macro subnavItem(item, isDevCollection) %}
   {% set isActive = page.url === item.url %}
   {% set hasActive = functions.isActivePath(page.url, item.url) %}
   {% set isDraft = [].concat(item.data.tags).includes('draft') %}
 
-  <li class="sidebar-nav-secondary-item sidebar-nav-item-container {{ 'draft' if isDraft }}"
+  <li class="sidebar-nav-secondary-item sidebar-nav-item-container"
       {% if hasActive %}aria-selected="true"{% endif %}>
     <div class="sidebar-nav-item-heading sidebar-nav-item-heading-secondary {{ 'active' if hasActive }}">
       <a class="sidebar-nav-secondary-link"
-         {% if isActive %}aria-current="page"{% endif %} {% if isDraft %}rel="nofollow"{% endif %}
+         {% if isActive %}aria-current="page"{% endif %} {% if isDraft or isDevCollection %}rel="nofollow"{% endif %}
          href="{{ item.url | url }}">
-        {{ badgeByTags(item.data.tags, isDraftCollection) }}
+        {{ badgeByTags(item.data.tags, isDevCollection) }}
         {{ item.data.name }}
       </a>
       <esl-trigger class="sidebar-nav-item-trigger sidebar-nav-item-arrow"
@@ -77,31 +79,31 @@
     <esl-panel class="sidebar-nav-secondary {{ 'open' if hasActive }}"
                {% if hasActive %}data-open{% endif %}
                fallback-duration="400">
-      {{ linkList(item.children, isDraftCollection) }}
+      {{ linkList(item.children, isDevCollection) }}
     </esl-panel>
   </li>
 {% endmacro %}
 
-{% macro link(item, isDraftCollection) %}
+{% macro link(item, isDevCollection) %}
   {% set isActive = page.url === item.url %}
   {% set isDraft = [].concat(item.data.tags).includes('draft') %}
 
-  <li class="sidebar-nav-secondary-item {{ 'active' if isActive }} {{ 'draft' if isDraft }}"
+  <li class="sidebar-nav-secondary-item {{ 'active' if isActive }}"
       {% if isActive %}aria-selected="true"{% endif %}>
     <a class="sidebar-nav-secondary-link"
-       {% if isActive %}aria-current="page"{% endif %} {% if isDraft %}rel="nofollow"{% endif %}
+       {% if isActive %}aria-current="page"{% endif %} {% if isDraft or isDevCollection %}rel="nofollow"{% endif %}
        href="{{ item.url | url }}">
       {{ badgeByTags(item.data.tags, isDraftCollection) }}
       {{ item.data.name }}
     </a>
   </li>
 {% endmacro %}
 
-{% macro badgeByTags(tags, isDraftCollection) %}
+{% macro badgeByTags(tags, isDevCollection) %}
   {# Tags checks ordered by priority, due to displaying single badge #}
   {% if tags.includes('deprecated') %}
     <span class="badge badge-sidebar badge-img badge-deprecated" title="Deprecated component" aria-label="Deprecated component"></span>
-  {% elif tags.includes('draft') and not isDraftCollection %}
+  {% elif tags.includes('draft') and not isDevCollection %}
     <sup class="badge badge-sidebar badge-sup badge-danger" title="Just a draft version of the page">draft</sup>
   {% elif tags.includes('beta') %}
     <sup class="badge badge-sidebar badge-sup badge-warning" title="Beta version (could change in a minor update)">beta</sup>

site/views/_includes/navigation/sidebar.njk

@@ -23,29 +23,15 @@
             </a>
           </div>
         </li>
-        <li class="sidebar-nav-item">
-          {{ navItem ('Introduction', 'introduction', 'static/assets/sidebar/intro.svg') }}
-        </li>
-        <li class="sidebar-nav-item">
-          {{ navItem ('Core', 'core', 'static/assets/sidebar/utils.svg') }}
-        </li>
-        <li class="sidebar-nav-item">
-          {{ navItem ('Components', 'components', 'static/assets/sidebar/components.svg') }}
-        </li>
-        <li class="sidebar-nav-item">
-          {{ navItem ('Examples', 'examples', 'static/assets/sidebar/examples.svg') }}
-        </li>
-        {% set releasedBlogs = collections.blogs | released %}
-        {% if releasedBlogs.length %}
-        <li class="sidebar-nav-item">
-          {{ navItem ('Blogs', 'blogs', 'static/assets/sidebar/blogs.svg') }}
-        </li>
-        {% endif %}
-        {% if env.isDev or functions.isActivePath(page.url, 'draft') %}
-          <li class="sidebar-nav-item">
-            {{ navItem ('Drafts', 'draft', 'static/assets/common/flask.svg') }}
-          </li>
-        {% endif %}
+
+        {% for item in collections.nav | sortBy('order') %}
+          {% set isNoEmpty = collections[item.data.collection] | released | exclude('data.collection') | length %}
+          {% set isActive = env.isDev or functions.isActivePath(page.url, item.data.collection) %}
+
+          {% if isNoEmpty or (isNoEmpty and isActive) %}
+            {{ navItem (item.data.title, item.data.collection, item.data.icon) }}
+          {% endif %}
+        {% endfor %}
 
         <hr class="sidebar-nav-item-divider show-xs"/>
 

site/views/_layouts/content.njk

@@ -9,8 +9,9 @@
     {% set isMarkdownSource = page.templateSyntax.includes('md') %}
     <div class="content {{ containerCls or 'container' }} {{ 'container-aside' if aside }} {{ 'markdown-container' if isMarkdownSource }}">
       {% if title %}
+        {% include 'navigation/breadcrumbs.njk' %}
         <h1 class="page-title">
-          {% if collectionIcon %}{% include "static/assets/" + collectionIcon %}{% endif %}
+          {% if icon %}{% include "static/assets/" + icon %}{% endif %}
           {{ title | safe }}
           {% if 'beta' in [].concat(tags) %}<span class="badge badge-sup badge-warning">Beta</span>{% endif %}
           {% if 'draft' in [].concat(tags) %}<span class="badge badge-sup badge-danger">Draft</span>{% endif %}

site/views/blogs/index.njk

@@ -2,11 +2,10 @@
 layout: collection-grid
 title: Blogs
 name: See All
-order: 1000
+order: 10
 collection: blogs
 hidden: true
 list: true
-tags: [blogs]
-collectionIcon: sidebar/blogs.svg
-eleventyExcludeFromCollections: true
+tags: [nav, blogs]
+icon: sidebar/blogs.svg
 ---

site/views/components/index.njk

@@ -3,11 +3,12 @@ layout: collection-grid
 title: Components List
 seoTitle: Components List of Exadel Smart Library (ESL)
 name: All
-order: -1
+order: 3
 collection: components
+tags: [nav]
 hidden: true
 list: true
-collectionIcon: sidebar/components.svg
+icon: sidebar/components.svg
 eleventyImport:
   collections: ["components"]
 ---

site/views/core/index.njk

@@ -3,11 +3,12 @@ layout: collection-grid
 title: Core
 seoTitle: Utility list of Exadel Smart Library (ESL)
 name: All
-order: -1
+order: 2
 collection: core
 hidden: true
 list: true
-collectionIcon: sidebar/utils.svg
+tags: [nav]
+icon: sidebar/utils.svg
 eleventyImport:
   collections: ["core"]
 ---