Add hexdoc_smart_var, generate GitHub repo link in navbar if no custo…

…m links are configured (close #26)

CHANGELOG.md

@@ -4,6 +4,17 @@ 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
+
+* New Jinja template filter: `hexdoc_smart_var`
+  * Can be used to allow runtime variable lookups based on values in `props.template.args`. This is currently used by the [custom navbar links](https://hexdoc.hexxy.media/docs/guides/template/#navbar) feature.
+
+### Changed
+
+* A GitHub link is now added to the navbar by default (fixes [#26](https://github.com/hexdoc-dev/hexdoc/issues/26)). See the [docs](https://hexdoc.hexxy.media/docs/guides/template/#navbar) for more info.
+
 ## `1!0.1.0a19`
 
 ### Added

noxfile.py

@@ -518,6 +518,7 @@ def dummy_setup(session: nox.Session):
                     ]
                     right = [
                         { text="Right", href="https://google.ca", icon="box-arrow-up-left" },
+                        { text="GitHub", href.variable="source_url" },
                     ]
                     """
                 ),

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

@@ -64,18 +64,18 @@
 {%- endmacro %}
 
 {% defaultmacro navbar_link(data) -%}
-  {% set external = data.external|default(true) %}
-  {% set icon = data.icon|default("box-arrow-up-right" if external else false) %}
+  {% set external = data.external|default(true)|hexdoc_smart_var %}
+  {% set icon = data.icon|default("box-arrow-up-right" if external else false)|hexdoc_smart_var %}
   <li>
     <a
-      href="{{ data.href }}"
+      href="{{ data.href|hexdoc_smart_var }}"
       {% 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>
+    >{{ data.text|hexdoc_smart_var|safe }}{% if icon %} <i class="bi bi-{{ icon }} external-link-icon"></i>{% endif %}</a>
   </li>
 {%- enddefaultmacro %}

src/hexdoc/core/properties.py

@@ -60,8 +60,16 @@ def asset_url(self) -> URL:
 
         return (
             URL("https://raw.githubusercontent.com")
-            / self.repo_owner
-            / self.repo_name
+            / self.github_repository
+            / self.github_sha
+        )
+
+    @property
+    def source_url(self) -> URL:
+        return (
+            URL("https://github.com")
+            / self.github_repository
+            / "tree"
             / self.github_sha
         )
 

src/hexdoc/jinja/__init__.py

@@ -2,9 +2,16 @@
     "IncludeRawExtension",
     "hexdoc_item",
     "hexdoc_localize",
+    "hexdoc_smart_var",
     "hexdoc_texture",
     "hexdoc_wrap",
 ]
 
 from .extensions import IncludeRawExtension
-from .filters import hexdoc_item, hexdoc_localize, hexdoc_texture, hexdoc_wrap
+from .filters import (
+    hexdoc_item,
+    hexdoc_localize,
+    hexdoc_smart_var,
+    hexdoc_texture,
+    hexdoc_wrap,
+)

src/hexdoc/jinja/filters.py

@@ -103,3 +103,23 @@ def hexdoc_item(
         id,
         context=cast(dict[str, Any], context),  # lie
     )
+
+
+@pass_context
+@make_jinja_exceptions_suck_a_bit_less
+def hexdoc_smart_var(context: Context, value: Any):
+    """Smart template argument filter.
+
+    If `value` is of the form `{"!Variable": str(ref)}`, returns the value of the
+    template variable called `ref`.
+
+    Otherwise, returns `value` unchanged.
+    """
+
+    match value:
+        case {**items} if len(items) != 1:
+            return value
+        case {"variable": str(ref)}:
+            return context.resolve(ref)
+        case _:
+            return value

src/hexdoc/jinja/render.py

@@ -29,6 +29,7 @@
 from .filters import (
     hexdoc_item,
     hexdoc_localize,
+    hexdoc_smart_var,
     hexdoc_texture,
     hexdoc_wrap,
 )
@@ -108,6 +109,7 @@ def create_jinja_env_with_loader(loader: BaseLoader):
         "hexdoc_localize": hexdoc_localize,
         "hexdoc_texture": hexdoc_texture,
         "hexdoc_item": hexdoc_item,
+        "hexdoc_smart_var": hexdoc_smart_var,
     }
 
     return env
@@ -194,6 +196,7 @@ def render_book(
         "site_url": str(props.env.github_pages_url),
         "relative_site_url": relative_site_url,
         "page_url": str(page_url),
+        "source_url": str(props.env.source_url),
         "version": version,
         "lang": lang,
         "lang_name": lang_name,
@@ -205,6 +208,11 @@ def render_book(
         "safari_pinned_tab_color": "#332233",
         "minecraft_version": minecraft_version or "???",
         "full_version": plugin.full_version,
+        "navbar": {  # default navbar links (ignored if set in props)
+            "center": [
+                {"text": "GitHub", "href": {"variable": "source_url"}},
+            ],
+        },
         "_": lambda key: hexdoc_localize(  # i18n helper
             key,
             do_format=False,

test/integration/__snapshots__/test_copier/test_index[vlatestmainen_usindex.html].raw

@@ -75,6 +75,16 @@
     </div>
     <div class="collapse navbar-collapse" id="navbar-collapse">
       <ul class="nav navbar-nav navbar-right">
+            <li>
+    <a
+      href="https://github.com/GITHUB_REPOSITORY/tree/GITHUB_SHA"
+        target="_blank"
+      class="navbar-link"
+      role="button"
+      aria-haspopup="true"
+      aria-expanded="false"
+    >GitHub <i class="bi bi-box-arrow-up-right external-link-icon"></i></a>
+  </li>
         <li class="dropdown">
           <a
             href=""

test/integration/__snapshots__/test_main_1.19/test_files[vlatestmainen_usindex.html].raw

@@ -75,6 +75,16 @@
     </div>
     <div class="collapse navbar-collapse" id="navbar-collapse">
       <ul class="nav navbar-nav navbar-right">
+            <li>
+    <a
+      href="https://github.com/GITHUB_REPOSITORY/tree/GITHUB_SHA"
+        target="_blank"
+      class="navbar-link"
+      role="button"
+      aria-haspopup="true"
+      aria-expanded="false"
+    >GitHub <i class="bi bi-box-arrow-up-right external-link-icon"></i></a>
+  </li>
         <li class="dropdown">
           <a
             href=""

test/integration/__snapshots__/test_main_main/test_files[vlatestmainen_usindex.html].raw

@@ -75,6 +75,16 @@
     </div>
     <div class="collapse navbar-collapse" id="navbar-collapse">
       <ul class="nav navbar-nav navbar-right">
+            <li>
+    <a
+      href="https://github.com/GITHUB_REPOSITORY/tree/GITHUB_SHA"
+        target="_blank"
+      class="navbar-link"
+      role="button"
+      aria-haspopup="true"
+      aria-expanded="false"
+    >GitHub <i class="bi bi-box-arrow-up-right external-link-icon"></i></a>
+  </li>
         <li class="dropdown">
           <a
             href=""

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

@@ -22,7 +22,7 @@ right = [
 ]
 ```
 
-![A screenshot of a navbar generated with the above configuration](example.png)
+![A screenshot of a navbar generated with the above configuration](navbar_example.png)
 
 ### Fields
 
@@ -32,3 +32,85 @@ right = [
 |`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 `box-arrow-up-right` (<ExternalLinkIcon />).||
+
+:::tip
+
+All of the above fields support [smart variables](#smart-variables).
+
+:::
+
+### Default links
+
+If the `template.args.navbar` field is not present in `hexdoc.toml`, the following default value will be used:
+
+```toml title="doc/hexdoc.toml"
+[template.args.navbar]
+center = [
+    { text="GitHub", href.variable="source_url" },
+]
+```
+
+![A screenshot of a navbar generated using the default configuration, showing an external GitHub link](navbar_default.png)
+
+:::note
+
+The variable `source_url` contains a permalink to the GitHub commit tree that the book was generated from.
+
+:::
+
+To disable the default navbar links, you can add an empty navbar section to `hexdoc.toml`:
+
+```toml title="doc/hexdoc.toml"
+[template.args.navbar]
+```
+
+## Smart variables
+
+Some fields in `template.args` support the use of smart variables. These can be used to look up template variable values at runtime that are not known in advance.
+
+For example, the following [navbar](#navbar) snippet would generate a link pointing at the value of the `source_url` variable when the navbar is generated (eg. `https://github.com/hexdoc-dev/hexdoc/tree/abcdef`):
+
+```toml title="doc/hexdoc.toml"
+[template.args.navbar]
+center = [
+    { text="GitHub", href.variable="source_url" },
+]
+```
+
+:::note
+
+The following TOML and JSON snippets are logically equivalent:
+
+```toml
+href.variable = "source_url"
+href = { variable = "source_url" }
+```
+
+```json
+{
+    "href": {
+        "variable": "source_url"
+    }
+}
+```
+
+:::
+
+On the other hand, the following snippet would generate a link pointing at the literal text `source_url` (ie. an invalid link):
+
+```toml title="doc/hexdoc.toml"
+[template.args.navbar]
+center = [
+    { text="GitHub", href="source_url" },
+]
+```
+
+:::tip
+
+Smart variables are implemented using the [`hexdoc_smart_var`](pathname:///docs/api/hexdoc/jinja.html#hexdoc_smart_var) filter, provided by hexdoc. You can use it in your own templates as follows:
+
+```jinja
+{{ variable_name|hexdoc_smart_var }}
+```
+
+:::