[generation] chunk a module file per class/section #458
Description
This is an idea that goes back from my initial proposal (nodejs/next-10#166) for a revamped metadata for API docs. This initiative is on hold as it is pending on the work this tooling provides so we can start revamping metadata. (@flakey5 and @Ethan-Arrowood also gave suggestions of metadata standards/formats)
The main issue I'm trying to address is as much optimized we can make the generated output, it doesn't change the fact that some api docs pages are extremely lengthy and big. Although we could attempt splitting the output content into multiple chunks (separated files addressing different sections) so for example v8.md becomes a bunch of v8-{sectionName}.html. This would solve each HTML page beign ridiculously long.
It would require of course a configuration of redirects (platform-specific, be it a Vercel config file with a bunch of HTTP 307's) or platform-agnostic, a bunch of HTML-redirects. (HTML files that pretty much have a redirect tag)
These redirects would be generated at generator time so that if someone goes to https://nodejs.org/api/v8.html#new-deserializerbuffer it would redirect them to https://nodejs.org/api/v8-class-v8-deserializer.html#new-deserializerbuffer
We would also need to introduce the same sort of breadcrumbs that we have on Node.js's Learn pages (Previous / About) so that users can easily go to the next/previous section of, i.e., v8 docs, and the navigation would also need to be redone in a way that we have these subsections navigating to these new pages.
This is of course a complex "solution" to break down pages into smaller content. The idea is not just make loading pages faster as reported here but also reduce the strain on users to find what they want in one page, endless scroll pages, and they're also heavy on the rendering-side.
Q/A
- In the example above would there still be a real v8.html page?
- No, since we need to respect the topology and order of the content, sections would always have their own page. The first section of v8.html would effectively be v8.html or a redirect to v8-{firstSection}.html
- This is also needed so that the redirects work, because if a v8.html still exists, these redirects per # wouldn't work. I'm also not sure we can do HTTP redirects that include a hashtag, to be honest. Otherwise we would need a middleware that is actually running in a server tha grabs old URLs into the new ones...)
- What is considered a section?
- Any H2 entry that has at least more than one children. For example on the image below, everything from V8 to before "Serialization API" would be the first section. Everything under Serialization API would be another section.
- On another example, 'crypto.html', everything before "Class: Certificate" would be the first section, and each class (Certificate, Cihperiv, Decipheriv) would be individual sections.
- Any H2 entry that has at least more than one children. For example on the image below, everything from V8 to before "Serialization API" would be the first section. Everything under Serialization API would be another section.