Improve nav_list helper to be used with any type of navigation list defined in navigation.yml data file

- Add documentation
- Close #272

_data/navigation.yml

@@ -1,3 +1,24 @@
+# example navigation
+foo:
+  - title: "Parent Link 1"
+    url: /parent-1-page-url/
+    children:
+      - title: "Child Link 1"
+        url: /child-1-page-url/
+      - title: "Child Link 2"
+        url: /child-2-page-url/
+
+  - title: "Parent Link 2"
+    url: /parent-2-page-url/
+    children:
+      - title: "Child Link 1"
+        url: /child-1-page-url/
+      - title: "Child Link 2"
+        url: /child-2-page-url/
+      - title: "Child Link 3"
+        url: /child-3-page-url/
+
+
 # main links links
 main:
   - title: "Quick-Start Guide"
@@ -18,54 +39,54 @@ docs:
   - title: Getting Started
     children:
       - title: "Quick-Start Guide"
-        path: quick-start-guide
+        url: /docs/quick-start-guide/
       - title: "Structure"
-        path: structure
+        url: /docs/structure/
       - title: "Installation"
-        path: installation
+        url: /docs/installation/
       - title: "Upgrading"
-        path: upgrading
+        url: /docs/upgrading/
 
   - title: Customization
     children:
       - title: "Configuration"
-        path: configuration
+        url: /docs/configuration/
       - title: "Navigation"
-        path: navigation
+        url: /docs/navigation/
       - title: "UI Text"
-        path: ui-text
+        url: /docs/ui-text/
       - title: "Authors"
-        path: authors
+        url: /docs/authors/
       - title: "Layouts"
-        path: layouts
+        url: /docs/layouts/
 
   - title: Content
     children:
       - title: "Working with Posts"
-        path: posts
+        url: /docs/posts/
       - title: "Working with Pages"
-        path: pages
+        url: /docs/pages/
       - title: "Working with Collections"
-        path: collections
+        url: /docs/collections/
       - title: "Helpers"
-        path: helpers
+        url: /docs/helpers/
       - title: "Utility Classes"
-        path: utility-classes
+        url: /docs/utility-classes/
 
   - title: Extras
     children:
       - title: "Stylesheets"
-        path: stylesheets
+        url: /docs/stylesheets/
       - title: "JavaScript"
-        path: javascript
+        url: /docs/javascript/
 
   - title: Meta
     children:
       - title: "History"
-        path: history
+        url: /docs/history/
       - title: "Contributing"
-        path: contributing
+        url: /docs/contributing/
       - title: "Old 2.2 Docs"
-        path: docs-2-2
+        url: /docs/docs-2-2/
       - title: "License"
-        path: license
+        url: /docs/license/

_docs/13-helpers.md

@@ -174,3 +174,75 @@ To include an [auto-generated table of contents](http://kramdown.rubyforge.org/c
 ```liquid
 {% raw %}{% include toc icon="gears" title="My Table of Contents" %}{% endraw %}
 ```
+
+## Navigation List
+
+Include an unordered list of links to be used as sidebar navigation with the `nav_list` helper.
+
+**1.** Start by adding a set of titles and URLs to `_data/navigation.yml` in the same way the [`main` navigation]({{ base_path }}/docs/navigation/) is built.
+
+`foo` navigation example:
+
+```yaml
+# _data/navigation.yml
+foo:
+  - title: "Link 1 Title"
+    url: /link-1-page-url/
+
+  - title: "Link 2 Title"
+    url: http://external-link.com
+
+  - title: "Link 3 Title"
+    url: /link-3-page-url/
+
+  - title: "Link 4 Title"
+    url: /link-4-page-url/
+```
+
+For a navigation list that has child pages you'd structure the YAML like this:
+
+```yaml
+# _data/navigation.yml
+foo:
+  - title: "Parent Link 1"
+    url: /parent-1-page-url/
+    children:
+      - title: "Child Link 1"
+        url: /child-1-page-url/
+      - title: "Child Link 2"
+        url: /child-2-page-url/
+
+  - title: "Parent Link 2"
+    url: /parent-2-page-url/
+    children:
+      - title: "Child Link 1"
+        url: /child-1-page-url/
+      - title: "Child Link 2"
+        url: /child-2-page-url/
+      - title: "Child Link 3"
+        url: /child-3-page-url/
+```
+
+**2:** On the page(s) you'd like the `foo` sidebar nav add the following YAML Front Matter, referencing the same key name.
+
+```yaml
+sidebar:
+  nav: "foo"
+```
+
+**ProTip:** If you're applying the same navigation list to several pages setting it as a [Front Matter default](https://jekyllrb.com/docs/configuration/#front-matter-defaults) is the better option.
+{: .notice--info}
+
+The theme's documentation is built with the `nav_list` helper so if you'd like an example to dissect take a look at `navigation.yml`, `_config.yml` and `_doc/` in the [`gh-pages` branch]({{ site.gh_repo }}/gh-pages/) of this repo.
+
+To add a navigation list to a post or page's main content instead of the sidebar use the include this way:
+
+```liquid
+{% raw %}{% include nav_list nav="foo" %}{% endraw %}
+```
+
+{% include nav_list nav="foo" %}
+
+| Parameter | Required     | Description |
+| --------- | --------     | ----------- |
+| items     | **Required** | Name of the links array found in `_data/navigation.yml`. |

_includes/nav_list

@@ -1,21 +1,42 @@
 {% include base_path %}
-{% assign navigation = site.data.navigation[page.sidebar.nav] %}
+{% assign navigation = site.data.navigation[include.nav] %}
 
 <nav class="nav__list">
   {% if page.sidebar.title %}<header><h4 class="nav__title" style="padding: 0;">{{ page.sidebar.title }}</h4></header>{% endif %}
   <ul>
     {% for nav in navigation %}
-      <li><span class="nav__sub-title">{{ nav.title }}</span>
+      <li>
+        {% if nav.url %}
+          {% comment %}internal/external URL check{% endcomment %}
+          {% if nav.url contains "http" %}
+            {% assign domain = "" %}
+          {% else %}
+            {% assign domain = base_path %}
+          {% endif %}
+
+          <a href="{{ domain }}{{ nav.url }}"><span class="nav__sub-title">{{ nav.title }}</span></a>
+        {% else %}
+          <span class="nav__sub-title">{{ nav.title }}</span>
+        {% endif %}
+
         {% if nav.children != null %}
         <ul>
           {% for child in nav.children %}
-          {% assign nav_url = child.path | prepend: "/" | prepend: page.sidebar.nav | prepend: "/" | append: "/" %}
+            {% comment %}internal/external URL check{% endcomment %}
-            {% if nav_url == page.url %}
+            {% if child.url contains "http" %}
+              {% assign domain = "" %}
+            {% else %}
+              {% assign domain = base_path %}
+            {% endif %}
+
+            {% comment %}set "active" class on current page{% endcomment %}
+            {% if child.url == page.url %}
               {% assign active = "active" %}
             {% else %}
               {% assign active = "" %}
             {% endif %}
-            <li><a href="{{ nav_url | prepend: base_path }}" class="{{ active }}">{{ child.title }}</a></li>
+
+            <li><a href="{{ domain }}{{ child.url }}" class="{{ active }}">{{ child.title }}</a></li>
           {% endfor %}
         </ul>
         {% endif %}
@@ -23,3 +44,5 @@
     {% endfor %}
   </ul>
 </nav>
+
+

_includes/sidebar.html

@@ -18,7 +18,7 @@
       {% if s.text %}{{ s.text | markdownify }}{% endif %}
     {% endfor %}
     {% if page.sidebar.nav %}
-      {% include nav_list items=page.sidebar.nav %}
+      {% include nav_list nav=page.sidebar.nav %}
     {% endif %}
   {% endif %}
   </div>