-
Notifications
You must be signed in to change notification settings - Fork 2.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
redoc-cli: Generate HTML *with* dependencies #540
Labels
Comments
Thanks for the detailed write-up. That makes lots of sense. PR's are welcome |
While |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
First off, I recognize and appreciate the use of being able to generate a single dependency-less HTML file that contains all your documentation. What I'm suggesting is a feature to compliment that functionality, not replace it.
I'm really glad to see
redoc-cli bundle
has been introduced as an alternative to client-side rendering. As an extreme example, Discord's client-side docs take about 50 seconds to load for me, and that number drops to about 5 seconds with prerendering. For smaller API specs, the page load is nearly instant.However, the generated HTML file still has some low-hanging fruit for optimization. Rendering with
--cdn=true
helps, but there are still a number of resources that could be referenced as external files to better leverage caching in both the browser and on the server. In a production environment, the convenience and portability of a zero-dependency HTML file isn't really a factor, and improving page performance takes priority.Right off the bat, I noticed that the original spec is included as a massive inline base64 blob for downloading. Continuing with Discourse as an example, their minified JSON spec weighs in at around 300k. If this is gzipped to be sent to the browser on its own, it compresses down to about 43k. But with the bundled version, it is instead base64'd, causing it to balloon to 400k. Even if you then gzip the resulting HTML, that base64 still takes up ~71k (base64 text doesn't compress as well as the original spec). All of this is ignoring the fact that, unless the user actually wants to download the spec, it doesn't need to be included in the page at all.
Less critical -- but still desirable -- would be the ability to reference all the other non-HTML assets as external resources as well. This essentially just means the putting style rules at the top of the page in a
.css
file, and putting the initial declaration of__redoc_state
in its own.js
file. This would allow those files to be cached by a user's browser, which is nice for documentation that is likely to be accessed frequently by the same user.Further down the road, this could also potentially enable a scenario where CSS could be generated to be shared between multiple pages documenting different APIs. It looks like the generated CSS isn't always the same right now, but that would be great for a site that hosts documentation for multiple APIs.
The text was updated successfully, but these errors were encountered: