Redocly / Redocly/redoc

redoc-cli: Generate HTML *with* dependencies

Open
#540 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the redoc-cli bundle entry point and inspect how --cdn=true, the inline base64 specification, CSS, and __redoc_state are written into the generated HTML. Define the output for dependency-backed bundles, including externally referenced assets and the existing dependency-less mode, then verify that bundled documentation still renders and the specification remains downloadable when requested.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, documentation, performance
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.