Bookshelf feature

[Coi-l]

Background

A while ago the need to bundle together multiple mdBooks arose for me. I did some digging but I could only find a number of feature requests in the issues list. So I decided to try and prototype something myself. Adding a 'shelf' command to the CLI.

Strategy

The feature is based around a shelf.toml file which contains a number of books to include in your bookshelf. They can either be locally present on the filesystem or a git repository. If you use a git repository you can optionally provide a path inside git repository where the file is present and a branch.

These books are then build by the shelf command.

In addition to this one more book is built, the actual "shelf". This is also an mdBook. It will will contain an index and a separate page for each book containing a bit more information.

Every book built by the shelf command will have an additional icon in the top right corner of a book. Clicking this will bring you back to the bookshelf.

It is the fa-book icon. I would have liked to use something more like this: https://fontawesome.com/icons/books?f=classic&s=solid but all those seem to be "Pro".

You can see a working example here:

https://coi-l.github.io/mdBook/bookshelf/index/book/index.html
or here:
https://coi-l.github.io/mdBook/bookshelf-multi/index/book/index.html

These to sites display the two options available. The first simple one with just one "shelf" in the bookshelf, and the seconds with multiple "shelves". This second option can be used to categorize the mdBooks.

Trying it out

You can try this out for yourself by checking out the PR code and building the mdBook binary.
Then navigate to the 'test_shelf' directory where there is a shelf.toml file prepared. Run the mdBook binary with 'shelf' as the command. This will build the same bookshelf as provided in the link above.

Summing it up

What I am looking for is comments regarding the PR.
First and foremost if this is something that is desired. There seems to be a number of feature requests for this, but maybe this strategy is not the way to go about it?

If you think this sounds like a good way forward I'd appreciate feedback on the code and on the actual design of the shelf book and UI in general. I don't mind polishing this to make it look good. Perhaps tables would be better or something.

Maybe the book icon in the books should produce a dropdown instead so you can easily select another book, or move back to the bookshelf.

The actual directory structure that the shelf command produces can also be adjusted.

Issues I think are requesting something like this, but I might have misunderstood:

#1748
#1347
#1666
#1042

[shenef]

Looking at your example, it seems there are some sub-pages where the "Return to shelf" URL is not generated correcly.
Instead of using
https://coi-l.github.io/mdBook/shelf/book/index.html some of them use
https://coi-l.github.io/mdBook/books/shelf/book/index.html which results in a 404.
In the rust documentation book it works correctly on every page i tried but in the mdbook docs and the test book there are some pages that have the wrong URL and some that have the correct one.

[Coi-l]

Looking at your example, it seems there are some sub-pages where the "Return to shelf" URL is not generated correcly. Instead of using https://coi-l.github.io/mdBook/shelf/book/index.html some of them use https://coi-l.github.io/mdBook/books/shelf/book/index.html which results in a 404. In the rust documentation book it works correctly on every page i tried but in the mdbook docs and the test book there are some pages that have the wrong URL and some that have the correct one.

Yes, you are correct. Using relative paths was not a good idea.
I've updated the code and the link to the example with a fix for this.

Thanks for the feedback!

[ksd3]

Out of curiosity, was this ever merged? This is the exact thing I'm looking for.

[Coi-l]

Out of curiosity, was this ever merged? This is the exact thing I'm looking for.

No. I haven't really gotten any kind of response from the maintainers unfortunately.

Have you tried it? Did it work well for you?

[ksd3]

Out of curiosity, was this ever merged? This is the exact thing I'm looking for.

No. I haven't really gotten any kind of response from the maintainers unfortunately.

Have you tried it? Did it work well for you?

I'm new to Rust, so I don't quite know how to even get it to work. I'm fine with downgrading my version of mdbook - could you provide instructions on how to install it?

[Coi-l]

Out of curiosity, was this ever merged? This is the exact thing I'm looking for.

No. I haven't really gotten any kind of response from the maintainers unfortunately.
Have you tried it? Did it work well for you?

I'm new to Rust, so I don't quite know how to even get it to work. I'm fine with downgrading my version of mdbook - could you provide instructions on how to install it?

I wouldn't recommend installing this instead of the official one. But if you want to try it out you can clone the repository and do a cargo build. That will give you the binary with the 'shelf' command included. And in the 'test_shelf' directory there is a toml file you can adapt.

[ksd3]

Out of curiosity, was this ever merged? This is the exact thing I'm looking for.

No. I haven't really gotten any kind of response from the maintainers unfortunately.
Have you tried it? Did it work well for you?

I'm new to Rust, so I don't quite know how to even get it to work. I'm fine with downgrading my version of mdbook - could you provide instructions on how to install it?

I wouldn't recommend installing this instead of the official one. But if you want to try it out you can clone the repository and do a cargo build. That will give you the binary with the 'shelf' command included. And in the 'test_shelf' directory there is a toml file you can adapt.

Wasn't this implemented only half a year ago?...I don't think too many features have been added to mdbook after it - but yeah, worst case scenario, I just run a script that produces the bookshelf rather than having it in an executable