Support external navigation links (#876)

Based on #238, resolves #66.

_config.yml

@@ -87,6 +87,11 @@ aux_links_new_tab: false
 # nav_sort: case_insensitive # default, equivalent to nil
 nav_sort: case_sensitive # Capital letters sorted before lowercase
 
+# External navigation links
+nav_external_links:
+  - title: Just the Docs on GitHub
+    url: https://github.com/just-the-docs/just-the-docs
+
 # Footer content
 # appears at the bottom of every page's main content
 

_includes/icons/external_link.html

@@ -0,0 +1,5 @@
+<!-- Feather. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
+<symbol id="svg-external-link" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-external-link">
+  <title id="svg-external-link-title">(external link)</title>
+  <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line>
+</symbol>

_includes/nav.html

@@ -104,6 +104,15 @@
       {%- endunless -%}
     {%- endif -%}
   {%- endfor -%}
+  {%- assign nav_external_links = site.nav_external_links -%}
+  {%- for node in nav_external_links -%}
+    <li class="nav-list-item external">
+      <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
+        {{ node.title }}
+        {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
+      </a>
+    </li>
+  {%- endfor -%}
 </ul>
 
 {%- if page.collection == include.key -%}

_layouts/default.html

@@ -38,6 +38,7 @@ layout: table_wrappers
         <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
       </svg>
     </symbol>
+    {% include icons/external_link.html %}
   </svg>
 
   <div class="side-bar">

_sass/navigation.scss

@@ -44,6 +44,12 @@
         }
       }
 
+      &.external > svg {
+        width: $sp-4;
+        height: $sp-4;
+        vertical-align: text-bottom;
+      }
+
       &.active {
         font-weight: 600;
         text-decoration: none;

docs/configuration.md

@@ -106,6 +106,11 @@ aux_links_new_tab: false
 heading_anchors: true
 ```
 
+## External navigation links
+
+External links can be added to the navigation through the `nav_external_links` option.
+See [Navigation Structure]({{ site.baseurl }}{% link docs/navigation-structure.md %}#external-navigation-links) for more details.
+
 ## Footer content
 
 ```yaml

docs/navigation-structure.md

@@ -246,6 +246,25 @@ aux_links:
 
 ---
 
+## External Navigation Links
+
+To add external links to the navigation, add them to the `nav_external_links` [configuration]({{ site.baseurl }}{% link docs/configuration.md %}) option in your site's `_config.yml` file.
+External links will appear under all other items in the listing order.
+
+#### Example
+
+{: .no_toc }
+
+```yaml
+# External navigation links
+nav_external_links:
+  - title: Just the Docs on GitHub
+    url: https://github.com/just-the-docs/just-the-docs
+    hide_icon: false # set to true to hide the external link icon - defaults to false
+```
+
+---
+
 ## In-page navigation with Table of Contents
 
 To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.