From 009a0f9c5a236fb5d6a2708928a909fd122d3fe0 Mon Sep 17 00:00:00 2001 From: SPGoding 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 b0f9310..5944d04 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 0000000..1592be6 --- /dev/null +++ b/_includes/icons/external_link.html @@ -0,0 +1,5 @@ + + + (external link) + + diff --git a/_includes/nav.html b/_includes/nav.html index a2aa2d6..3881008 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 -%} +
  • + + {{ node.title }} + {% unless node.hide_icon %}{% endunless %} + +
    • + {%- endfor -%} {%- if page.collection == include.key -%} diff --git a/_layouts/default.html b/_layouts/default.html index 63e23b0..a09a2a4 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -38,6 +38,7 @@ layout: table_wrappers + {% include icons/external_link.html %}
    diff --git a/_sass/navigation.scss b/_sass/navigation.scss index 0e67349..2077336 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 cb0b7fd..041805c 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 9d481bd..b67369c 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 `
      ` 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.