From 33ba8d8eaa0fec848b1e637b04d05bcb57383066 Mon Sep 17 00:00:00 2001
From: CarbonNeuron <16768821+CarbonNeuron@users.noreply.github.com>
Date: Wed, 4 Oct 2023 14:10:56 -0500
Subject: [PATCH] Add configuration options for opening external links in new
 tab (#1360)

I've whipped up a solution that solves #1103. I've added a config option `nav_external_links_new_tab`, which is off by default. When turned on, it'll pop external nav links into a new tab. The idea was borrowed from how [aux_nav.html](https://github.com/just-the-docs/just-the-docs/blob/main/_includes/components/aux_nav.html) does it with `aux_links_new_tab`.

---------

Co-authored-by: Matt Wang <matt@matthewwang.me>
---
 CHANGELOG.md                       | 11 +++++++++++
 _includes/components/sidebar.html  |  6 +++---
 _includes/components/site_nav.html |  8 ++++++--
 docs/navigation-structure.md       |  8 ++++++++
 4 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45418dc..104331e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,10 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
+### New Features
+
+- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360]
+
 ### Bugfixes
 
 - Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356]
@@ -26,8 +30,15 @@ Code changes to `main` that are *not* in the latest release:
 [#1358] moved `_includes/nav.html` to the `_includes/components` directory,
 Users who were overriding that file will need to adjust their sites accordingly.
 
+### New Contributors
+
+- [@CarbonNeuron] made their first contribution in [#1360]
+
+[@CarbonNeuron]: https://github.com/CarbonNeuron
+
 [#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356
 [#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358
+[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360
 
 ## Release v0.6.2
 
diff --git a/_includes/components/sidebar.html b/_includes/components/sidebar.html
index 4ccea2b..13c755b 100644
--- a/_includes/components/sidebar.html
+++ b/_includes/components/sidebar.html
@@ -4,7 +4,7 @@
   Results in: HTML for the side bar.
   Includes:
     title.html, components/site_nav.html, nav_footer_custom.html
-  Overwrites: 
+  Overwrites:
     nav_footer_custom.
   Should not be cached, because nav_footer_custom.html might depend on page.
 {%- endcomment -%}
@@ -16,9 +16,9 @@
       <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
     </button>
   </div>
-  
+
   {% include_cached components/site_nav.html %}
-  
+
   {% capture nav_footer_custom %}
     {%- include nav_footer_custom.html -%}
   {% endcapture %}
diff --git a/_includes/components/site_nav.html b/_includes/components/site_nav.html
index 9a3f8ee..e3c2d1d 100644
--- a/_includes/components/site_nav.html
+++ b/_includes/components/site_nav.html
@@ -4,7 +4,7 @@
   Results in: HTML for the site-nav.
   Includes:
     components/nav.html
-  Overwrites: 
+  Overwrites:
     pages_top_size, collections_size, collection_entry,
     collection_key, collection_value, collection.
 {%- endcomment -%}
@@ -22,7 +22,11 @@
     <ul class="nav-list">
       {%- for node in site.nav_external_links -%}
         <li class="nav-list-item external">
-          <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
+          <a href="{{ node.url | absolute_url }}" class="nav-list-link external"
+            {% if node.opens_in_new_tab or (node.opens_in_new_tab == nil and site.nav_external_links_new_tab) %}
+              target="_blank" rel="noopener noreferrer"
+            {% endif %}
+          >
             {{ 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>
diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md
index 23af9b0..046d67d 100644
--- a/docs/navigation-structure.md
+++ b/docs/navigation-structure.md
@@ -271,11 +271,19 @@ 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
+    opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
 ```
 
 The external links are decorated by an icon, which distinguishes them from internal links.
 You can suppress the icon by setting `hide_icon: true`.
 
+By default, external links are not opened in a new tab. However, this can be enabled by:
+
+1. setting `opens_in_new_tab: true` in the link's configuration object
+2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
+
+When they conflict, `opens_in_new_tab` takes precedence.
+
 ---
 
 ## In-page navigation with Table of Contents