just-the-docs / just-the-docs

A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
https://just-the-docs.com
MIT License
7.6k stars 3.68k forks source link

Add Prev and Next navigation buttons #1191

Open AnderUstarroz opened 1 year ago

AnderUstarroz commented 1 year ago

You did an absolutely amazing job building this template. I Just have one suggestion thought, I really miss having a Prev and Next navigation buttons for a smooth navigation between pages. I mean this can be done manually of course, but having the app already knowing the order of the pages, shouldn't be too hard adding an option on _config.yml to enable/disable navigation arrows (ideally with customized text)

Describe the solution you'd like Adding < PREV and NEXT > navigation button support via _config.yml

Additional context Examples from some famous project.

pdmosses commented 1 year ago

@AnderUstarroz thanks for raising this issue. See https://github.com/just-the-docs/just-the-docs/pull/394#issuecomment-792901833 for the status of some previous work towards addressing it.

I really miss having a Prev and Next navigation buttons for a smooth navigation between pages. I mean this can be done manually of course, but having the app already knowing the order of the pages, shouldn't be too hard […]

The navigation of a website is a tree, and a particular order of visiting the pages might not be suitable for all sites. The order on the site you cited is for Next to descend a level, and ascend only after visiting all the lower pages. That works well for such a shallow (two-level) site when the visitor is expected to visit all the pages in a particular order; putting the Next link at the bottom of the page also assumes the visitor wants to read it. But for a multi-level[^1] documentation site, the deepest pages might provide only supplementary details, of little or no interest to some visitors.

My personal preference is for the Prev and Next buttons to stay at the same level, and to provide an Up button for ascending in the navigation. This is what I use for my CBS-beta project.

So perhaps the order of visiting should be configurable.

You're welcome to submit a new PR for supporting Prev and Next buttons in v0.4, but I suggest to clarify the design first.

[^1]: Just the Docs v0.4 is restricted to three navigation levels. PR #462 proposes general multi-level navigation, but I won't have time to discuss or update it until late April.

AnderUstarroz commented 1 year ago

mmh I think otherwise, being able to jump from one section to the next without having to use additional clicks for going up was really nice on Rust docs, but you made a valid point (some may not like it) therefore having a configurable behavior on _config.yml would make us all happy.

I don't think I'll be able to submit a PR any time soon, I am quite busy at the moment and I' would have to understand how this whole Jekyll template system works, but I'll try if I find some time.

Thanks for the quick answer.