Support for "next" and "previous" links

[gnarea]

It'd be great if there were links to the previous and next posts in every page (where applicable).

(By the way, thanks for the theme! I like it a lot)

[bitprophet]

Hey, sorry I missed this!

IIRC those next/previous links are a native part of Sphinx so the theme is probably just neglecting to spit them out in our customized templates.

I personally don't like that feature (I've never really felt documentation sites to be highly linear) but this theme is all about options, so I am +1 to identifying the best place to stick them & adding an option to enable.

[bitprophet]

FTR this is based around the next and prev variables autoinjected into templates by core Sphinx, see e.g. how RTD's theme handles it.

I faintly remember axing that...aha, here it is: 1fb8e2f

So in the original Armin/Kenneth theme it was a sidebar element (for an example see the bottom of sidebar on eg http://docs.python-requests.org/en/latest/user/advanced/#prepared-requests); in Dave/Eric's theme and the older Python doc theme (which I think is the 'basic' theme from Sphinx) it's above the footer.

Torn on which would work best when explicitly enabled; sidebar could just be reinstated as it was, but some decently visible links at bottom of main content section (like on the new RTD theme) might be cleaner since the sidebar is already pretty busy at times.

[xuhdev]

@bitprophet I'm not sure whether you have noticed, the actual added back next and prev feature does not work even for the simplest document... The output html files contain the lines in relations.html, but the browsers show nothing (Firefox and Chromium). I cannot really find out the reason, so can you please test it out? Thanks!

[bitprophet]

@xuhdev When I get to poking this I would definitely be making sure it functioned 100%! I'm not surprised that they're not appearing even when "enabled", I suspect the styling needs updating as well as the HTML.

[ghost]

Required feature, especially for step-by-step books. Waiting for it.

[bitprophet]

@moldcraft Feedback about which way to implement the reinstated links (see #18 (comment) for details) would be appreciated, esp given you have a strong use case for the feature! Thanks.

[MinchinWeb]

I stumbled across this and thought I would offer my two bits, in the hope that they will be helpful.

As a reader, I find the previous/next links very helpful for documentation. Documentation is often one of the better places to find answers to how to use the software/library in question. Often, the fast est way to response to my questions/bug to try to read/skim all the documentation. Other support channels (like asking a question on StackOverflow or filing an issue) tend to take longer. Order and organization of the pages on the site is less important that just having everything available via clicking 'next' from start to finish.

In terms of placement, I would recommend putting the previous/next links at both the top and the bottom of the page. The reason is that the two sets of links get different usecases. The bottom links are for my first time reading it through, front to back; I read to the bottom of the page and there's the link to send me forward. The links at the top of the page get used when I'm skimming, often trying to re-find a page I've already read.

For an example of how this might look, the Better theme has top and bottom links.

[exhuma]

I'm currently writing a book with the help of Sphinx, and the next/previous links are really essential for this use-case. I'm currently mucking about with my toc-tree and by doing so realised that the links are not there. I have, for now, switched to the read-the-docs theme but I find that alabaster makes for a better "book" theme. I also highly like the idea to have them at the top and bottom as @MinchinWeb mentioned.

[bitprophet]

Agree, I figure if somebody's content wants these enough to opt-in to them, having at both top and bottom is best.

[ofek]

@bitprophet Hey, great job on Alabaster!

I've been stuck on this for an entire day. How exactly do you add content (in this case next/prev) after rendered page? I have this:

/_templates/layout.html

{% extends '!layout.html' %}

{% block footer %}
  <ul class="footer_nav">
      {%- if prev %}
        <li class="prev">
          Previous topic: <a href="{{ prev.link|e }}">{{ prev.title }}</a>
        </li>
      {%- endif %}

      {%- if next %}
        <li class="next">
          Next topic: <a href="{{ next.link|e }}">{{ next.title }}</a>
        </li>
      {%- endif %}
  </ul>
{% endblock %}

The issue here is it replaces the footer. How can this be added right after/be part of the main rendered text?

I'd really appreciate any insight you may have!

[jfbu]

See this reply to @ofek question. Sort of a clutch of course much less satisfying than @MinchinWeb's #101. Pointing out the link because I encountered today again the same problem and had forgotten my own answer ;-)

[jfbu]

@xuhdev @bitprophet regarding #18 (comment) in my brief testing the alabaster.css contains

div.relations {
    display: none;
}

I used a file _static/custom.css

div.relations {
    display: block;
}

and tested the effect with

html_sidebars = {
    '**': [
        # 'about.html',
        # 'navigation.html',
        'relations.html',
        # 'searchbox.html',
        # 'donate.html',
    ]
}

in conf.py. Your comments are old, and issue long solved I guess, posting nevertheless.

(the navigation.html needs no such css tweak)

Sorry, I overlooked the 'show_related' theme option.

[jab]

Just found my way to this 3+-year-old issue, and noticed that last April @MinchinWeb submitted a PR (#101) whose screenshots appear to do just what everyone interested in this issue is asking for.

Unfortunately it wasn't reviewed or merged before conflicts with master occurred.

Any maintainers watching this have a moment to comment, review, or at least mark as WONTFIX?

Thanks for the great work on Alabaster 😊

[jab]

Meant to say, what prompted me to find this issue was reports that users had missed some of my docs pages that are currently linked only in the sidebar, who wouldn't have missed them if they'd been linked in a horizontal next/prev nav under the current page content, as implemented in #101.