Deep-linking chunked docs - possible enhancement

[oddhack]

We use the chunker on the Vulkan Specification and it's a great tool for us - the single HTML page version of this document is beyond ridiculously huge and slow to load. The recent reimplementation was a godsend to the spec editor (me) due to performance improvements. So, we're very grateful to have it available.

That said,it would be really helpful for our purposes to have stable chapter naming - the spec evolves rapidly and chapters are added periodically - so instead of chap7.html we could have 'synchronization.html'. What this would let us do is create stable deep links into particular chapters from other Vulkan documentation, which isn't possible today. At best, we could do HTML postprocessing to construct a (section/anchor, page filename) map that has to be consumed by other tools operating on the other docs.

For our documents, the 'id' attributes generated by asciidoctor would be a fine chapter naming convention - of course if the chapter gets split further than it would require either 'id-id.html' naming convention or 'id-sectnum', so it's not trivial to make this robust when combined with the different nesting depths that can be specified through the command line (likewise specifying the nesting depths in terms of the chapter name instead of the chapter number would complete the pairing).

I don't have any idea how generally useful this would be, or if it's something you would be receptive to implementing. But as a first step, wanted to ask if you would be receptive to this approach, or have alternate suggestions to the same end?

(N.b. it is a shame that webservers don't have enough information to be able to rewrite HTML anchors in URLs, since that's all done browser-side).

[wshito]

Hi, thank you for your feedback. Your request should be useful since the other similar tool, asciidoctor-multipage, takes your strategy for the file naming. I didn't take that way simply because I mostly write documents in Japanese which would make the URL look awful if I don't put ids on every single headings because the heading titles become the ids automatically by asciidoctor when I produce HTML.

I haven't looked at the code yet so I don't know how hard it is to implement. I am currently busy being involved in some projects. So you might have to wait some time.

Until then, we should discuss how the URLs for nesting pages should look like.

[wshito]

@oddhack I have started to work on this enhancement. Please give me some time because I want to do refactoring first. If you have any more request, feel free to drop lines here for this occasion.

Meanwhile, encourage your people to leave stars on my project! That'll help me a lot! 😉