Allow adding custom links to the web book navbar

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/index.md

@@ -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 />.||