Open pvande opened 6 days ago
The current limitation is that docs.page works with a runtime model in mind, whereby it queries the information it needs for the specific page being loaded - the downside of this is that it's not aware of "other files" outside of that request.
This means we'd need to first grab the config + markdown, parse the config, and query the API again to grab any additional files (e.g. docs/api-sidebar.json
).
This isn't impossible, but I'm somewhat conscious of overhead from API roundtrips. The duel or alternative approach I'm currently exploring is (tldr version):
docs
+ config), bundle and cache itThe benefits of this are:
The cons vs the current approach are:
I definitely appreciate the cost of an API roundtrip here, but I'm not convinced that would exclusively be a bad thing. For example, being able to chunk very large hierarchies has the potential to improve rendering times for sidebars with thousands of pages. (Truthfully, a similar approach seems as though it could improve times on any large resource, and superficially doesn't seem dissimilar to how embedded assets are handled.)
The approach you're describing also seems like it would work, though eagerly populating the cache also comes as a drawback for large documentation sets.
As some background, I'm looking to make docs.page work with automatically generated API documentation. The tool that I'm using to generate my docs is aware of the hierarchy being modeled, and can express that as JSON, but generally shouldn't be responsible for writing or updating the
docs.json
file.I'd ideally like to be able to manually maintain my own
docs.json
file — allowing for control over title, description, and some general navigation — and "embed" the generated navigation details myself.Strawman proposal:
I can also see this being useful for
variables
andtabs
as well, possibly elsewhere.