From 009a0f9c5a236fb5d6a2708928a909fd122d3fe0 Mon Sep 17 00:00:00 2001
From: SPGoding <SPGoding@outlook.com>
Date: Wed, 13 Jul 2022 00:24:54 -0500
Subject: [PATCH] Support external navigation links (#876)
Based on #238, resolves #66.
---
_config.yml | 5 +++++
_includes/icons/external_link.html | 5 +++++
_includes/nav.html | 9 +++++++++
_layouts/default.html | 1 +
_sass/navigation.scss | 6 ++++++
docs/configuration.md | 5 +++++
docs/navigation-structure.md | 19 +++++++++++++++++++
7 files changed, 50 insertions(+)
create mode 100644 _includes/icons/external_link.html
diff --git a/_config.yml b/_config.yml
index b0f93102..5944d041 100644
--- a/_config.yml
+++ b/_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
diff --git a/_includes/icons/external_link.html b/_includes/icons/external_link.html
new file mode 100644
index 00000000..1592be66
--- /dev/null
+++ b/_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>
diff --git a/_includes/nav.html b/_includes/nav.html
index a2aa2d66..38810086 100644
--- a/_includes/nav.html
+++ b/_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 -%}
diff --git a/_layouts/default.html b/_layouts/default.html
index 63e23b0c..a09a2a47 100644
--- a/_layouts/default.html
+++ b/_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">
diff --git a/_sass/navigation.scss b/_sass/navigation.scss
index 0e673497..20773367 100644
--- a/_sass/navigation.scss
+++ b/_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;
diff --git a/docs/configuration.md b/docs/configuration.md
index cb0b7fd3..041805c2 100644
--- a/docs/configuration.md
+++ b/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
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index 9d481bd3..b67369c6 100644
--- a/docs/navigation-structure.md
+++ b/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.
--
GitLab