[RFC] Options to have the full content in one page

[Clonkk]

• Content should be displayed in a single page
• ToC should be still be usable for navigation.

For that we need to :

• Combine the <main> section of generated html page into one file
• Adapt the navigation bar.

Or alternatively, this could be a new theme entirely; whichever is easier.

For reference to https://forum.nim-lang.org/t/8249.

[HugoGranstrom]

I like this idea, as an option. The problem is how it should be done, in the forum post, two people want to read the same documentation in these different formats. Should you be able to generate either a multi-page or a single-page. Or could they be combined so the TOC automatically adds a SinglePage entry at the top/bottom which leads to the single page (which needs its own TOC of course).

An alternative would be to add an option to the TOC DSL so that we add a way to specify which pages to include in a single-page. For example something like this:

concater("index", "data_viz/plotting", "basics/basic_units")

And then have an option for including every file in the single page.

Just some random thought.

[Clonkk]

Should you be able to generate either a multi-page or a single-page. Or could they be combined so the TOC automatically adds a SinglePage entry at the top/bottom which leads to the single page (which needs its own TOC of course).

An alternative would be to add an option to the TOC DSL so that we add a way to specify which pages to include in a single-page. For example something like this:

IMHO, It should be an exclusive or.

I'm not necessarily against the idea but doing partial concatenation of multiple source file is going to generate a lot of corner case and increase the complexityby a tenfold for little added value.

So I suggest we start simple, solve the base (most common problem) which is that people want single-page, searchable doc, then we'll see if expanding from there is worth it.

[HugoGranstrom]

IMHO, It should be an exclusive or.

I disagree simply because it doesn't solve the problem discussed there. In this case, it would be up to the writer to decide which layout to use, not the users who are the ones who would have the most differing preferences. I'm not saying we have to implement the both-case from the beginning, simply that I think it should be an option in the future when we have figured out how to do it.

I'm not necessarily against the idea but doing partial concatenation of multiple source file is going to generate a lot of corner case and increase the complexityby a tenfold for little added value.

Ok agreed, no fine-grained control. An all-or-nothing approach instead.

So I suggest we start simple, solve the base (most common problem) which is that people want single-page, searchable doc, then we'll see if expanding from there is worth it.

Agreed, simple to begin with and then we'll see what we end up with and take it from there 😄

[Clonkk]

@pietroppeter Any idea on how we can do this ?

[pietroppeter]

hi, back from vacation today, need to catch up on lots of stuff, but I will review this and give my take in the next few days!

[pietroppeter]

in the meantime, from a quick search I was able to find the relevant issue from mdbook (currently still open): https://github.com/rust-lang/mdBook/issues/988

[pietroppeter]

I think the easieast way to implement such a functionality currently would be to add a command to build the single page book from the multiple page book after the regular book has been generated. An option --single-page could be added to nimibook cli for task build. With that option after regular book generation the single page task should (we could decide the option only does the following and the user should have first called build with no options):

• for every toc element get the content of {{{ blocks }}} in the generated html (using a html parser based on structure of document.mustache)
• generated a new single page all_chapters (or we could reuse blocks) content using the different tocs (we probably could put a horizontal line between main sections), making sure we had anchors with slugified chapter title before each toc content (I do not think we need it to be wrapping the title)
• generate the new toc using the anchor references as hrefs
• generate the single page book; probably we can use the same template as document.mustache (or if we have to change something we can create a single_page.mustache).

this would be the base to get the single page behaviour. Additional stuff (remove the multi page html if you do not want it, add cross links from single page to multi page, ...) could be added later.

[HugoGranstrom]

I like this idea 👍 One thing I've been thinking about, is how to decide what to put in the <head> tag. For example, some pages might useLatex and some don't. The obvious choice then would be to add latex to the single-page as well, but how do we know that we should do it?

[pietroppeter]

I guess if you want to have the single page working you need to define all "options" at book level. We could probably add a context at book level that would be used to generate the single page document. (btw useLatex is not yet used in nimibook, currently the mustache still has the mathjax_support only)

[HugoGranstrom]

Sounds like a good compromise 👍 sounds like something you would like to do either way. Sort of the same as nbInit before but better

I hadn't even noticed latex was missing :o But $$ is indeed just rendered as text 🙈

[pietroppeter]

it appears someone has implemented the single page functionality in mdbook https://github.com/rust-lang/mdBook/issues/982 (in their own fork, not yet an open PR)