@jeffreycwitt thanks for the suggestion! generating links to the next and previous pages would surely be a nice enhancement. There are already links to those pages in the sidebar navigation menu (under the page titles), but having next and previous buttons at the top and bottom of each page body in a website does make it easier to go through all the pages in the right order. Moreover, the sidebar isn't visible on small screens while scrolling a page: to see the existing links to the next and previous pages, one currently has to scroll back to the top of the page and click on the menu button.

Next and previous buttons are a standard feature of posts on blogs or mailing lists, but I've personally found such buttons useful also when browsing documentation pages produced using Read the Docs, and I'd like to have this feature in Just the Docs (as a configurable option).

The suggested implementation clearly works well for the site shown in your screenshot. However, it appears to rely on several assumptions:

1. all pages are at the top level
2. the nav_order values are all integers
3. no nav_order value is used more than once
4. there are no gaps in the nav_order values
5. pages with no nav_order are excluded

The description and implementation of the navigation structure in Just the Docs avoids making any of those assumptions:

1. top-level pages can have children and grandchildren
2. nav_order values can also be floats or strings (site-wide)
3. the same nav_order values can be used at different levels, and for children of different parents
4. integer nav_order values need not be contiguous
5. pages with no explicit nav_order are included, and ordered by their titles

It seems the current PR works only when all pages in the navigation set nav_order to successive integers following a (depth-first pre-order) traversal of the hierarchy. For example, adding _includes/next_prev.html and including it in _layouts/default.html produces (mostly) incorrect next and previous links in the docs pages of the current release.

@pdmosses yes I completely agree about the assumptions required for it to work, namely:

• all pages are at the top level
• the nav_order values are all integers
• no nav_order value is used more than once
• there are no gaps in the nav_order values
• pages with no nav_order are excluded

My use case operates under these assumptions, so it works for me. I don't think I'll have time to make it more flexible for cases where the above assumptions are not met (at least until this is something my use cases demand).

Nevertheless, since it would definitely be a configuration feature, it could be turned off by default, but be turned on with a configuration switch by people who understand its limitations and can ensure that their site meets the above conditions.

In any case, maybe the pull request could be just considered a "feature request" with an example of how it might function.

(I love the "theme" by the way!!! kudos to everyone working on it)

It was quite easy to add the proposed feature to my re-implementation of PR #192 for recursive navigation.

My next-prev branch generalises the feature proposed in the present PR to mutli-level hierarchies.

The styling is just a quick hack, and needs improving (I'm not familiar with the CSS details). Putting the upper next-rev links to the right of any breadcrumbs should look OK. The lower next-prev links should probably be aligned with the top of the TOC.

The links appear to be correct for the theme docs.

I haven't yet tested that recursive includes don't overwrite local variables – it may be necessary to manipulate a stack of saved page arrays… 😟

The feature can be turned off by:

nav_next_prev: false

but that should probably be the default.

Maybe the first and last pages of each list should have up-links? For the first page, up could link to the parent; for the last page, it could link to the next of the parent.

To test this feature on your own site, set:

remote_theme: pdmosses/just-the-docs@next-prev

@pdmosses sounds great. I changed the remote them to remote_theme: pdmosses/just-the-docs@next-prev but got this error during build:

Liquid Exception: Liquid error (/private/var/folders/m2/hdg2v4rn1x10jd1qtglp_npwh_1nwb/T/jekyll-remote-theme-20200729-14028-ibnis7/_includes/nav/init.html line 14): Nesting too deep included in /_layouts/default.html jekyll 3.8.7 | Error: Liquid error (/private/var/folders/m2/hdg2v4rn1x10jd1qtglp_npwh_1nwb/T/jekyll-remote-theme-20200729-14028-ibnis7/_includes/nav/init.html line 14): Nesting too deep included

There definitely could be something wrong on my end. But I thought it might be worth mentioning.

Here's my site instance for reference: https://github.com/jeffreycwitt/pl399

@jeffreycwitt thanks for testing my branch – much appreciated!

I took a copy of your master branch, and updated it to settings that refer to remote_theme: pdmosses/just-the-docs@next-prev. I also removed your _layouts/default.html, which was shadowing mine. I was able to reproduce the build issue when using Jekyll 3.8.7; but the build issue disappeared when I updated to Jekyll 4.1.1.

After eliminating most of your source files, I finally noticed that Jekyll was processing three files that have no title! All files included in the Just-the-Docs navigation are actually required to have titles, and my code relies on their presence. (There is apparently a significant difference between Jekyll 3.8.7 and Jekyll 4 regarding nil values…)

Could you try adding either nav_exclude: true or non-nil title fields in the front matter of 404.html, index.md, and login.md? An alternative is to use exclude in the configuration (which may be best for the 404 page).

If that doesn't fix the build issue at your end, please create a branch with a version of your site that demonstrates the issue, so I can be sure of using the same settings when debugging.

@jeffreycwitt, I wrote:

All files included in the Just-the-Docs navigation are actually required to have titles, and my code relies on their presence.

In fact the Just-the-Docs navigation simply ignores pages with no title when creating the navigation. I've updated the rec-nav and next-prev branches of my fork to do that too (and added a test page with no title). When using pdmosses/just-the-docs@next-prev your site should now build OK without the changes I previously suggested. However, I haven't yet tried to polish the layout of the next/previous page links.

This is a great enhancement, thank you @jeffreycwitt! In addition to what @pdmosses wrote, could we add the pagination to the bottom of the page instead of the top?

@pmarsceill I don't think should be hard at all. I've put the include above and below the content, like so:

{% include next_prev.html %}
{{content}}
{% include next_prev.html %}

Works fine in my instance. I see the navigation when I'm at the top, but also see it when I've scrolled down to the end of the page.

Perhaps the config could be modified, so that users could control whether the include is added to the top, bottom, or both. I think "both" should be the default, as it seems most desirable to have it present at the top and at the bottom.

@jeffreycwitt Would you have time to develop this PR to work with the multi-level navigation used for the theme docs? It might be fairly straightforward to enhance the current nav.html to assign to your previous_page and next_page variables, so that you wouldn't need to determine the navigation order yourself. (My own attempt at generalising your code to multi-level navigation is based on an experimental fork for 'recursive' navigation, which is unlikely to be incorporated into a release in the near future.)

@pdmosses I can give it a shot. Maybe I can give it some time this weekend.

So, I'll try to up this PR to include your changes to support multi-level navigation. Then you can review the updated PR.

@pdmosses @pmarsceill checkout my most recent commits.

This is just one option whose main virtue is simplicity. The only change is that the loop now checks to see if there is a common parent before looking up the next and previous page for a given context page.

This seems to be enough to respect the multi-level navigation. Removing the first and third assumption. The other assumptions still apply, though they don't seem like unreasonable assumptions to me.

If you don't want make these assumptions then you could just set nav_next_prev to false

• all pages are at the top level
• the nav_order values are all integers
• no nav_order value is used more than once (no nav_order is more than once within the same parent
• there are no gaps in the nav_order values
• pages with no nav_order are excluded (this seems desirable to me, if you want it included in navigation, you should add a nav_order property)

you can preview it here: https://jeffreycwitt.com/just-the-docs

the solution of @pdmosses is much more sophisticated (and will handle much variation) but if you think its too involved to merge, this approach might be a simple temporary option until a more sophisticated approach can be merged.

ps. I also had to add gem "kramdown-parser-gfm" to my the Gemfile to get it to compile locally. I'm not sure why.

@jeffreycwitt thanks for the generalisation to multi-level navigation! I'll take a look at it. I hope it works well enough with the theme documentation pages.

My solution is definitely not an option at present, since it relies on allowing unlimited-depth ('recursive') navigation, and the details haven't yet been reviewed. Even if approved, a merge will probably have to wait for a new major version of the theme (although I think it is actually backwards-compatible with 0.3.1).

The styling that puts it in the same line as the breadcrumbs looks very good on the theme docs.

As I expected, there are no next or prev links on the child pages of Utilities, because they are ordered by their titles, and don't have nav_order fields. I have an idea for how to fix that; if it works, I'll get back to you with a suggested update.

Your branch built OK for me without the gem "kramdown-parser-gfm" that you'd added.

Minor releases of this theme generally aim for complete backwards compatibility, so the default for nav_next_prev should presumably be false until the next major release.

I wrote:

As I expected, there are no next or prev links on the child pages of Utilities, because they are ordered by their titles, and don't have nav_order fields. I have an idea for how to fix that; if it works, I'll get back to you with a suggested update.

The idea is to let nav.html set previous_page and next_page. It already creates the properly sorted pages_list, and loops through the hierarchy in the right order. It was straightforward to add a couple of auxiliary variables at each level to keep track of the current potential previous_page; when it finds a node with page.url, it sets previous_page, and leaves it to the following node (if any) to set next_page.

The implementation of the idea is a bit repetitive, because the code for the top level needs duplicating at the child and grandchild levels; with recursive navigation, no duplication was needed. But it works OK with the current 3-level navigation (I've tested it with some grandchildren), and it doesn't require the values of nav_order to be successive integers. It works also for the default ordering by title: for the current theme docs, Utilities automatically gets Next and Previous links.

I'm attaching the updated nav.html and next_prev.html in Archive.zip. The code in next_prev.html assumes that nav.html has already been executed, which is ensured by the default layout. A significant benefit of not doing any sorting of pages in next_prev.html is that the next/previous links are automatically consistent with the main navigation produced by nav.html.

Unless you see any drawbacks, I suggest to update the PR with these files. (I could try pushing the updates to the PR, but I don't have previous experience of doing that, and in any case I prefer to check that you don't have objections to the changes.)

@pdmosses That seems like a great solution. I'll integrate your changes in the Archive.zip and then push the new commit for your review.

@pdmosses have a look at the updated pull request and my working gh-pages, https://jeffreycwitt.com/just-the-docs/
I basically just copied the two files you sent me in the archive.zip.

Seems to work well for both pages with nav_order and those without (see working nav links in the "Utilities" section.)
I also merged the most recent commits on upstream master.

So if @pmarsceill likes it, seems like it could be merged.

P.s.
While best to restrict this PR to these changes some ideas for another PR might be to add the navigation to the bottom of the file. However I think that should be styled along with the "back to top" link, which would require some small re-organization of dom organization in the DOM layout.

Also it might be nice to have an "next/down" link when a page contains children or an "next/up" when you reach the end of the children list and want to go up to the next parent. (similarly for previous).

be to include and "up" or "parent" link so that if you reach the end

@jeffreycwitt Many thanks for the updates to the PR. I don't have sufficient knowledge of CSS to review the details of the styling myself, but it looks very good. I'm glad the code in nav.html appears to work as intended.

If this PR is merged in 0.3.2, you might follow up by submitting an issue with your suggested enhancements before proceeding to submit a further PR.

@jeffreycwitt have you considered using arrows instead of the words for the next and previous links? That might make them stand out a bit better, and look neater if you later add up and down.

I have previously used Hyperlatex to generate web pages from LaTeX sources, and it automatically adds arrows:

The arrows are included also at the bottom of each page. It has an option to change the behaviour of next so it automatically goes down and up, instead of staying at the same level.

@jeffreycwitt I've added a couple of minor comments on the changed files, and requested a review from @pmarsceill

I'm going to circle back on this one as I'd like to think about the visual styling a bit more... I think it is a valuable addition, perhaps to get into the next patch.

@pmarsceill Agreed. While it is nice to have the navigation at the top of the page, I think the navigation is most useful when at the bottom of the page. But I omitted the include here because I wasn't sure the best way to integrate the navigation styling with the already existing "back to the top" link. This also seems like a navigation function. So I think, with a little reorganization of the divs at the bottom, the next/prev links could easily be integrated in a way that is also consistent with their presentation at the top of the page.

@jeffreycwitt, I wrote:

The implementation of the idea is a bit repetitive, because the code for the top level needs duplicating at the child and grandchild levels; with recursive navigation, no duplication was needed.

I've now added this feature to my combination-rec-nav branch (which adds multi-level navigation to the branch used for the combination PR #578). This involved rather simple additions to two files (and adding a configuration option). The results can be seen (temporarily) at https://pdmosses.github.io/just-the-docs/.

I've moved the links for the previous and next pages to just above the auto-generated TOC of child pages, since they share the aim of giving quick access to closely-related pages. I've also added links to parent pages.

The link texts are configurable, and appear as arrows by default:

It would be easy to repeat the links at the top of the page, but as you wrote:

the navigation is most useful when at the bottom of the page

That is especially true on narrow displays, where the navigation panel is hidden.

Pages with has_toc: false do not show links to siblings or parents, since it seems likely that the intention is to remove all links from the bottom of the page. (There could be an option to display links to siblings and parents on pages with has_toc: false, but I doubt that it is needed.)

Comments and suggestions for improvement are welcome.

It would be easy to repeat the links at the top of the page

I've now done that. It makes it a lot easier to use the relative links to browse all the siblings of a page.

The CSS I used for the relative links is very basic, but appears to work – also with narrower displays:

(That screenshot shows Firefox; it seems Safari changes the top margin when narrowing the display, but I've no idea why...)

I've also changed the default arrow symbols, because Firefox was rendering them differently from Safari. (They should probably be replaced by SVGs, to avoid browser dependence.)

Hi all - if we're still interested in merging this PR in, I'm happy to work with us to get it up to speed.

Two options:

• retarget to v0.4.0, resolve merge conflicts, and I can provide feedback on styling & accessibility
• wait until v0.4.0 is released, and the same process

I'm not in a rush either way, though I think this is a great feature to implement! Let me know what y'all think!

(regardless, there will be several merge conflicts)

@mattxwang thanks for considering this PR for inclusion in v0.4.0!

Re styling and accessibility, I'm personally quite happy with the appearance of the prev-up-next links used in my combination-rec-nav branch. See the arrows at the top and bottom of https://pdmosses.github.io/just-the-docs/docs/ui-components/labels/ for an example of how it would look on the 3-level theme docs site. Conveniently, repeatedly clicking a left or right arrow takes you up when you get to the end of the siblings.

I personally dislike sites where the authors have decided to force you to go through the pages depth-first. It doesn't make much difference on a shallow site like the theme docs, but on a deep multi-level site, depth-first may require going through a lot of lower-level pages before getting to the next sibling on the current level. In any case, I don't think that depth-first is particularly appropriate for documentation sites.

@jeffreycwitt would you have time to retarget this PR to v0.4.0 and resolve merge conflicts, so that @mattxwang can provide feedback on styling & accessibility? If not, it will probably have to wait for a subsequent release.

Hm, for now I'm going to close this PR as stale. Feel free to re-open (or open a new PR) if you're interested in this feature!

(I don't think I'd be able to dedicate time to taking over the code for this PR)

@mattxwang I need next-prev for my project site. When I get time again, I'll focus first on #462, then I'll re-open this PR.

@mattxwang I need next-prev for my project site. When I get time again, I'll focus first on #462, then I'll re-open this PR.

Sounds good, looking forward to it!