Better multi-page mobile build support?

[bendtherules]

I have been reading the Ecmascript spec on mobile for some time. And IMO, it kinda works - but overall things felt somewhat retrofitted to work on mobile. I guess what i am saying is things could be much better on mobile. (is there some existing discussion around this?)

What i like about the workflow on desktop -

1. Everything loads in one-shot - Being a single page, once it is loaded - the whole spec is ready for reading and cross referencing. It's somewhat slow on desktop, but still understandable.
2. ecmarkup's built-in highlighting and cross-referencing tools - So, all the things like term highlighting within a section to permalink, pin, references - all of that is super helpful at times and shouldn't be dumbed down. (Maybe pinning could be synced somehow?)
3. Browser built-in search - Even though the above tools are good, they are not helpful while finding all references for say, a general method like LabelledEvaluation. ( I understand that's because there are multiple Implementations for that same method.) So, in those cases - i can just search for the word using browser's in-page search. Because it's single page, that works really well.

What i don't like about the experience on mobile -

1. Huge document - ⬆️ Most of these desktop features technically "work" on mobile. But because it's a huge document, everything gets slowed down on mobile - browser search is slow, loading page (network + rendering) is very slow, general cross-referencing is hard to do.
2. Unfriendly UI - There are a lot of small but repeating problems with the UI elements. For example - some monospaced texts (I don't know the type actually) gets cut off on the right, buttons like sidebar toggle are very small on mobile, elements have very odd size discrepancy (some elements look big enough for mobile, some just beside it is small like desktop), references bottom drawer is unusable (scrolling + size issue), sidebar is very small (so pins are also hard to use), etc.

So, in summary - ui could be much much better and inbuilt tools are somewhat less effective because of the huge document size. And they make the problem even worse together - imagine, if there was separate page for each major section, i could still use a small looking sidebar with less entries without tapping on the wrong entry or losing my position in the document.

Potential solutions

I don't expect these to be implemented in current form, but this is what i could think of. Doing even some of these things can hugely benefit the readers.

1. Section-wise pages - Each major section gets it's own url and page. The full page will exist separately. All the ecmarkup's tools needs to now support cross page referencing, states need to be maintained across pages (SPA-like) (ex. pins, references drawer need to maintain state).
   We should also add a cross-page search then (to replicate browser search within the whole document). Although, this is also doable by going separately to the full page on mobile and searching there.
2. Fix ui elements - We can just look at the individual ui elements which don't work well on mobile and fix them. Ideally, a mobile-first consideration will be helpful. This can be done independently of Section-wise pages, but they are more effective together.

I understand some of these are very big asks and probably even a deviation from the main focus of the tool, but IMO - this is (from a user's perspective) actually a documentation generation tool. And this documentation is meant to be read by a wide community on varying devices. The reader can really benefit from a cleaner and more usable ui.
For ex, consider how popular and useful https://pep8.org is - it is merely a reformatted and stylised version of the official pep8 proposal (which looks decent anyway).

I can also build a prototype to first demonstrate how useful this can be.

[bakkot]

See https://github.com/tc39/ecmarkup/issues/151 re: multipage support. I think we're in agreement that this would be useful (at least, I am), we just haven't yet had the time to work out the design and make it happen. I've been thinking about it a little but haven't started implementing it yet. Pull requests welcome!

Note also that there's a proposal to substantially restructure a lot of the specification (for unrelated reasons), which I'd want to land before making the multipage build so as to minimize broken links.

[bakkot]

Multipage builds are available as of https://github.com/tc39/ecmarkup/pull/301. I'm leaving this open to track any other mobile-specific issues.