Allow adding custom links to the web book navbar

Author: object-Object

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Pydantic's HISTORY.md](https://github.com/pydantic/pydantic/blob/main/HISTORY.md), and this project *mostly* adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [UNRELEASED]
+
+### Added
+
+* Allow adding custom links to the web book navbar ([docs](https://hexdoc.hexxy.media/docs/guides/template)).
+
 ## `1!0.1.0a18`
 
 ### Fixed

noxfile.py

@@ -507,6 +507,18 @@ def dummy_setup(session: nox.Session):
                     mod_name = "Dummy"
                     author = "author"
                     show_landing_text = true
+
+                    [template.args.navbar]
+                    left = [
+                        { text="<strong>Left</strong>", href="https://google.ca" },
+                    ]
+                    center = [
+                        { text="Center 1", href="https://google.ca", external=false },
+                        { text="Center 2", href="https://google.ca", external=false, icon="box-arrow-down-right" },
+                    ]
+                    right = [
+                        { text="Right", href="https://google.ca", icon="box-arrow-up-left" },
+                    ]
                     """
                 ),
                 "nodemon.json": {

src/hexdoc/_templates/components/navbar.html.jinja

@@ -1,6 +1,7 @@
+{% import "macros/formatting.html.jinja" as fmt with context -%}
+
 <nav class="navbar navbar-default navbar-static-top">
   <div class="container">
-    <!-- toggle and name -->
     <div class="navbar-header">
       <button
         type="button"
@@ -17,9 +18,19 @@
       <a class="navbar-brand" href="{{ relative_site_url }}">{{ _("hexdoc."~props.modid~".title") }}</a>
     </div>
 
-    <!-- content -->
     <div class="collapse navbar-collapse" id="navbar-collapse">
+      {% set navbar = navbar|default({}) %}
+      {% if navbar.left|default(false) %}
+        <ul class="nav navbar-nav navbar-left">
+          {% for item in navbar.left %}
+            {{ fmt.navbar_link(item) }}
+          {% endfor %}
+        </ul>
+      {% endif %}
       <ul class="nav navbar-nav navbar-right">
+        {% for item in navbar.center|default([]) %}
+          {{ fmt.navbar_link(item) }}
+        {% endfor %}
         <li class="dropdown">
           <a
             href=""
@@ -42,6 +53,9 @@
           >{{ lang_name }} <span class="caret"></span></a>
           <ul class="dropdown-menu dropdown-menu-left" id="lang-dropdown"></ul>
         </li>
+        {% for item in navbar.right|default([]) %}
+          {{ fmt.navbar_link(item) }}
+        {% endfor %}
       </ul>
     </div>
   </div>

src/hexdoc/_templates/index.css.jinja

@@ -381,6 +381,12 @@ p.todo-note {
   border-radius: 6px 0 6px 6px;
 }
 
+.external-link-icon {
+  position: relative;
+  bottom: 2px;
+  margin-left: 2px;
+}
+
 .nobr {
   white-space: nowrap;
 }

src/hexdoc/_templates/macros/formatting.html.jinja

@@ -62,3 +62,20 @@
     <span class="collapse-recipe-hide">{{ _(base_key~".hide") }}</span>
   </summary>
 {%- endmacro %}
+
+{% defaultmacro navbar_link(data) -%}
+  {% set external = data.external|default(true) %}
+  {% set icon = data.icon|default("box-arrow-up-right" if external else false) %}
+  <li>
+    <a
+      href="{{ data.href }}"
+      {% if external %}
+        target="_blank"
+      {% endif %}
+      class="navbar-link"
+      role="button"
+      aria-haspopup="true"
+      aria-expanded="false"
+    >{{ data.text|safe }}{% if icon %} <i class="bi bi-{{ icon }} external-link-icon"></i>{% endif %}</a>
+  </li>
+{%- enddefaultmacro %}

web/docusaurus/docs/03-guides/03-template/_external_link_icon.md

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-box-arrow-up-right" viewBox="0 0 16 16">
+  <path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5"/>
+  <path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0z"/>
+</svg>

web/docusaurus/docs/03-guides/03-template/example.png

@@ -0,0 +1,34 @@
+import ExternalLinkIcon from "./_external_link_icon.md";
+
+# Template Features
+
+Some parts of the web book template can be customized by setting values in [`template.args`](pathname:///docs/api/hexdoc/core/properties.html#TemplateProps.args).
+
+## Navbar
+
+To add links to the navbar, add something like this to `hexdoc.toml`:
+
+```toml title="doc/hexdoc.toml"
+[template.args.navbar]
+left = [
+    { text="<strong>Left</strong>", href="https://google.ca" },
+]
+center = [
+    { text="Center 1", href="https://google.ca", external=false },
+    { text="Center 2", href="https://google.ca", external=false, icon="box-arrow-down-right" },
+]
+right = [
+    { text="Right", href="https://google.ca", icon="box-arrow-up-left" },
+]
+```
+
+![A screenshot of a navbar generated with the above configuration](example.png)
+
+### Fields
+
+|Key|Type|Description|Required?|
+|---|----|-----------|---------|
+|`text`|string/html|Text to be displayed in the navbar. May contain HTML.|✅|
+|`href`|string|Link URL to open.|✅|
+|`external`|boolean|If `true` (the default), this link will open in a new tab.||
+|`icon`|string|[Bootstrap icon id](https://icons.getbootstrap.com) to display. If `external` is `true`, defaults to <ExternalLinkIcon />.||