Single-page version of Handbook?

[flexibeast]

Can/should we provide a single-page version of the Handbook? A user on IRC asked if there was one, and it seems to me that it would make it easier for users to search for particular terms within the Handbook.

Related: the above user noted that it was annoying to go to a page in the Handbook and find that it contained only a brief overview of the section. In a single-page version, i imagine this would be fine; but if we started adding ToCs for subsections (cf. #234), that might end up being unwieldy in a single-page version.

@ericonr, @bobertlo, thoughts?

[ericonr]

I kinda really want ToC for all pages, but I see how it could be bad to have it for this specific matter. The blocker for a single page version is mdBook, otherwise most of the links won't work at all. I know there's an experimental backend for epubs, at least.

Anyway, how would we provide it? A download perhaps?

A user on IRC asked if there was one, and it seems to me that it would make it easier for users to search for particular terms within the Handbook.

There is a search bar, and it actually worked pretty well for me. Do you know if they tried it?

Related: the above user noted that it was annoying to go to a page in the Handbook and find that it contained only a brief overview of the section.

I agree. I think some sections could lose the index.md page entirely, possibly. But ToCs should alleviate the issue.

[Vaelatern]

I like single page versions when I want to have all the docs on a slow network connection, or when not connected to any network.

[flexibeast]

@ericonr:

The blocker for a single page version is mdBook, otherwise most of the links won't work at all.

Ah, so mdBook can't output a single-page version? We'd have to script something to munge everything (including links) into a single-page format?

Anyway, how would we provide it? A download perhaps?

No, i was thinking there would be a link to the single-page version on the landing page.

There is a search bar, and it actually worked pretty well for me. Do you know if they tried it?

The user hadn't mentioned searching; it was just something that came to mind when i thought about it. (i hadn't tried the search functionality myself, but i just did so now, and it seemed fine.) The concern the user had was basically having to continually select the next section, instead of being able to simply scroll.

I agree. I think some sections could lose the index.md page entirely, possibly. But ToCs should alleviate the issue.

*nod* And if we would have to script conversion to a single-page version anyway, stripping ToCs could be part of that process.

[jeffayle]

Here's a very rough ruby script that generates one html page out of the docs: https://gist.github.com/jeffayle/b84d32e9ef5d62c7733f395fa43ec058 It should be run in the root of the docs repository.

Here's sample output: https://gist.githubusercontent.com/jeffayle/6bc97ea1aabf122d0c58cf6b4e1bc579/raw/22a02ff6e74a8bbaeb7975f8cb8bfccfde01edbc/doc.html (which I guess you'll have to save and reopen because github won't show gists as html?)

Links between documents are fixed, but links to sections of documents are broken. I probably won't do anymore work on this.

I think the biggest issue that will go into making this something worthwhile is how deep the headings go. You generally don't want to go past the third or fourth level, but some individual pages have pretty deep headings and some pages are pretty deep in the table of contents.

The outputted html technically creates the correct html5 outline, but that means almost nothing in terms of actual accessibility.

edit: Okay, I did work on it a bit more. Most of the links are working now, except a few that are pointing to a .html instead of .md. There are still lots of problems with the output. The markdown interpreter I'm using isn't quite compatible with the docs. This script is just a hack. This should probably be implemented as an mdbooks plugin. Those hacky regular expressions are all dealing with things that mdbooks should have an internal api to deal with in a nice way. If mdbooks has a good plugin api the only complexity is in putting all the files in the right order, wrapped up in the method Page#render. If mdbooks stores these internally as a tree then this reduces to

(contents) (children)

.

[flexibeast]

Wow, this is looking great - thank you!

Alternative mdBook backends are passed a JSON representation. i'm not familiar enough with Rust to make an assessment of the API, but i think @ericonr might be.

[jeffayle]

That JSON actually gets us most of the way. It has all the chapters in a tree structure, so we could do something like (pseudo-ruby)

def render chapter
    return if chapter == nil
    puts "<section id=\"section id\"">"
    puts chapter.to_html
    chapter.sub_items.each { |sub_chapter| render sub_chapter.chapter }
    puts "</section>"
end

The only other thing that needs to be done is to render the markdown to html and rewrite the links. The html renderer is already doing this (.md -> .html) so there should be something that can be tapped into to support this.

[ericonr]

There's this backend as well: https://crates.io/crates/mdbook-epub

It doesn't generate reasonable results yet, though.

@jeffayle damn, that's cool! With some CSS it could look really good.

@flexibeast I have very little experience with Rust, unfortunately. Would be interested in learning more, but we'd probaly end up with a whole new backend for mdBook (not a terrible result). Writing just a small tool to integrate with @jeffayle's script for the rendering could work very well too. I'm not sure how soon I can tackle this, but would it be okay wtith you if I stole some of your logic?

[jeffayle]

we can use about half of the mdbook plugin api without using rust. if none of us know rust, that's probably the way to go. In book.toml add

[output.custom]
command = "whatever command to run"

The command you give gets a big json file with all the contents of the book. You can check out that file by setting command="cat". That command has to render the markdown into html though, which is most likely going to be going through a different rendering engine than the one mdbook uses. However, mdbook uses one following the CoreMark standard, so we should be able to get away with using something else as long as it also follows CoreMark. Ideally, this rendering engine would have the options to rewrite links and rewrite section anchors.

but would it be okay wtith you if I stole some of your logic?

yes, please do! I think Page#content might be the only part that ends up being helpful, that's where the link rewriting is happening, and this is probably the best (compromise between correctness and effort) way to do it if it can't be injected right into a markdown parser. I'm going to go back over the script though and comment it better.. I just looked at it again, and it's bad.