Enable option for relbars

Provides *next* and *previous* links above and below main page content. They are disabled by default. Includes documentation.
Closes #18.

Author: minchinweb

alabaster/layout.html

@@ -12,7 +12,30 @@
   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
 {% endblock %}
 
-{# Disable base theme's top+bottom related navs; we have our own in sidebar #}
+{# top+bottom related navs; we also have our own in sidebar #}
+{%- macro rellink_markup() %}
+  <nav id="rellinks">
+    <ul>
+      {%- if prev %}
+        <li>
+          &larr;
+          <a href="{{ prev.link|e }}" title="Previous document">{{ prev.title }}</a>
+        </li>
+      {%- endif %}
+      {%- if next %}
+        <li>
+          <a href="{{ next.link|e }}" title="Next document">{{ next.title }}</a>
+          &rarr;
+        </li>
+      {%- endif %}
+    </ul>
+  </nav>
+{%- endmacro %}
+
+{%- set theme_show_relbar_top = theme_show_relbar_top or theme_show_relbars %}
+{%- set theme_show_relbar_bottom = theme_show_relbar_bottom or theme_show_relbars %}
+
+{# removed existing top+bottom related nav, and embed in main content #}
 {%- block relbar1 %}{% endblock %}
 {%- block relbar2 %}{% endblock %}
 
@@ -26,9 +49,29 @@
       {%- if render_sidebar %}
         <div class="bodywrapper">
       {%- endif %}
+
+          {%- block relbar_top %}
+            {%- if theme_show_relbar_top|tobool %}
+              <div class="related top">
+                &nbsp;
+                {{- rellink_markup () }}
+              </div>
+            {%- endif %}
+          {% endblock %}
+
           <div class="body" role="main">
             {% block body %} {% endblock %}
           </div>
+
+          {%- block relbar_bottom %}
+            {%- if theme_show_relbar_bottom|tobool %}
+              <div class="related bottom">
+                &nbsp;
+                {{- rellink_markup () }}
+              </div>
+            {%- endif %}
+          {% endblock %}
+
       {%- if render_sidebar %}
         </div>
       {%- endif %}

alabaster/static/alabaster.css_t

@@ -49,6 +49,8 @@
 {%- set theme_narrow_sidebar_link = theme_narrow_sidebar_link or theme_gray_3 %}
 {%- set theme_sidebar_hr = theme_sidebar_hr or theme_gray_3 %}
 
+{%- set theme_relbar_border = theme_relbar_border or theme_gray_2 -%}
+
 
 @import url("basic.css");
 
@@ -704,3 +706,50 @@ table.docutils.citation, table.docutils.citation td, table.docutils.citation th
   -webkit-box-shadow: none;
   box-shadow: none;
 }
+
+
+/* relbar */
+
+.related {
+    line-height: 30px;
+    width: 100%;
+    font-size: 0.9rem;
+}
+
+.related.top {
+    border-bottom: 1px solid {{ theme_relbar_border }};
+    margin-bottom: 20px;
+}
+
+.related.bottom {
+    border-top: 1px solid {{ theme_relbar_border }};
+}
+
+.related ul {
+    padding: 0;
+    margin: 0;
+    list-style: none;
+}
+
+.related li {
+    display: inline;
+}
+
+nav#rellinks {
+    float: right;
+}
+
+nav#rellinks li+li:before {
+    content: "|";
+}
+
+nav#breadcrumbs li+li:before {
+    content: "\00BB";
+}
+
+/* Hide certain items when printing */
+@media print {
+    div.related {
+        display: none;
+    }
+}

alabaster/theme.conf

@@ -27,6 +27,9 @@ sidebar_includehidden = true
 sidebar_collapse = true
 show_powered_by = true
 show_related = false
+show_relbars = false
+show_relbar_top =
+show_relbar_bottom =
 
 gray_1 = #444
 gray_2 = #EEE
@@ -119,3 +122,4 @@ code_highlight = #FFC
 page_width = 940px
 sidebar_width = 220px
 fixed_sidebar = false
+relbar_border =

docs/changelog.rst

@@ -2,6 +2,9 @@
 Changelog
 =========
 
+* :feature:`18` add optional *next* and *previous* links at the top and bottom
+  of page content. Use theme option ``show_relbars`` to enable these. Credit:
+  William Minchin.
 * :release:`0.7.10 <2017-02-28>`
 * :bug:`32` Update styling of various block-level elements such as admonitions
   (``.. note::``, ``.. warning::``, etc) and code blocks (``.. code::``) so

docs/customization.rst

@@ -158,6 +158,10 @@ Variables and feature toggles
   main body of the page scrolls but the sidebar remains visible. (Applies only
   to desktop window sizes; the mobile view is unaffected.) Defaults to
   ``false``.
+* ``show_relbars``: ``true`` or ``false`, defaults to ``false`` - used to
+  display *next* and *previous* links above and below the main page content. If
+  you only want to display one, this setting can be further overriden through
+  the ``show_relbar_top`` and ``show_relbar_bottom`` settings.
 
 Style colors
 ------------
@@ -208,6 +212,8 @@ colorscheme. The more granular settings can be used to override as needed.
 * ``narrow_sidebar_fg``: Text color of same.
 * ``narrow_sidebar_link``: Link color of same. Defaults to ``gray_3``.
 * ``code_highlight``: Color of highlight when using ``:emphasize-lines:`` in a code block.
+* ``relbar_border``: Color of border between bar holding *next* and *previous*
+  links, the rest of the page content. Defulats to ``gray_2``.
 
 Fonts
 -----