5 ms·

I agree re: scroll hijacking and with a preference for minimal styling, while noting that the styling on docs.mux.com is pretty minimal compared to other docs s

I agree re: scroll hijacking and with a preference for minimal styling, while noting that the styling on docs.mux.com is pretty minimal compared to other docs sites. What I'm wondering is what the anti-React folks are recommending for generating HTML and/or DOM itself in the docs use case, since most of it needs to be dynamically generated from OpenAPI definitions.

Osiris 3y ago
Static file generation. People are suggesting that tooling creates HTML files from templates at compile time and then served as plain HTML.
- CipherThrowaway 3y ago
  Going by the response headers, it seems that most if not all of the HTML served by docs.mux.com consists of cacheable static files. As the OP article mentions, using React for static generation is one of the big use cases for RSC and Next. Which templating technology would you recommend for the use case instead? Keep in mind that generating HTML from OpenAPI specs can become complex and will require plenty of maps, filters, recursion and indexing into the data in the course of transforming it into HTML.
  - jmull 3y ago
    > plenty of maps, filters, recursion and indexing into the data Are there a lot of server side template languages that can’t do this? This is straight-forward stuff.
    - CipherThrowaway 3y ago
      > Are there a lot of server side template languages that can’t do this? Did I say there weren't a lot of template languages that can do this? A dead give-away that this subject isn't as "straight-forward" as you think is that, at one sentence in, you've already misidentified the conversation taking place. This isn't about can vs can't, but about the right tool for the job. What template language would you personally recommend for this project?
      - jmull 3y ago
        classic ASP
        CipherThrowaway 3y ago
        Maintaining VBScript sucked 100x worse than TypeScript. How would you approach SSG with Classic ASP?
        jmull 3y ago
        You’re moving the goalposts to a whole new stadium.
        CipherThrowaway 3y ago
        Classic HN conversation here. "The web is too complex! All these web frameworks are too complicated!" "Okay, what do you suggest instead?" "I'd just use [completely unmaintainable technology from the 90s that is no longer supported by its vendor]" "Okay, how would you approach [basic feature of the web framework]?" "Stop moving the goalposts!" Come on, you could at least come up with some hand-waving about cache headers and CDNs.
        phist_mcgee 3y ago
        You missed the classic, "I did this back in the 90s using x and it was more powerful and sane compared to any of this new malarkey"
tacker2000 3y ago
You can generate a swagger-ui doc page from an open api yaml spec by just mounting the file in their swaggerapi/swagger-ui docker container. Same with Redocly. Granted the pages probably wont look as good as what they have here or be integrated in their larger docs, but yea its possible.
- CipherThrowaway 3y ago
  To me, that is a separate level of decision. Sure, you could avoid the whole problem of building a docs generator by using an off-the-shelf docs generator, and letting the Redoc and Swagger dev teams deal with all the development complexity. But if you are going to build your own docs generator, React and Next with RSC aren't a bad choice. Web development just isn't as simplistic as people on HN seem to think it is.
  - Draiken 3y ago
    I agreed with most of your comment but this almost triggered me: > React and Next with RSC aren't a bad choice. Web development just isn't as simplistic as people on HN seem to think it is. Yes it fucking is. I've been doing it for 15+ years and most of the complexity added since about 10 years ago is not required. Many times they're actually regressions. The web is complex because we made it so. This is a perfect example where they could write their own docs generator with MUCH less complexity. You read a damn json/yaml file and make HTML out of it. Style it with CSS and you're finished. It's as maintainable as it gets. Now let's look at running `yarn install` in this project a year from now and see how easy it's going to be to maintain it. Odds are NextJS will be 5 versions behind and with 500 vulnerabilities found in the dependency graph.
    - tacker2000 3y ago
      You are of course right. But probably they got VC cash and some guy said, do it in React bla bla whatever the cost…

Osiris 3y ago

Static file generation. People are suggesting that tooling creates HTML files from templates at compile time and then served as plain HTML.

CipherThrowaway 3y ago
Going by the response headers, it seems that most if not all of the HTML served by docs.mux.com consists of cacheable static files. As the OP article mentions, using React for static generation is one of the big use cases for RSC and Next. Which templating technology would you recommend for the use case instead? Keep in mind that generating HTML from OpenAPI specs can become complex and will require plenty of maps, filters, recursion and indexing into the data in the course of transforming it into HTML.
- jmull 3y ago
  > plenty of maps, filters, recursion and indexing into the data Are there a lot of server side template languages that can’t do this? This is straight-forward stuff.
  - CipherThrowaway 3y ago
    > Are there a lot of server side template languages that can’t do this? Did I say there weren't a lot of template languages that can do this? A dead give-away that this subject isn't as "straight-forward" as you think is that, at one sentence in, you've already misidentified the conversation taking place. This isn't about can vs can't, but about the right tool for the job. What template language would you personally recommend for this project?
    - jmull 3y ago
      classic ASP
      - CipherThrowaway 3y ago
        Maintaining VBScript sucked 100x worse than TypeScript. How would you approach SSG with Classic ASP?
        jmull 3y ago
        You’re moving the goalposts to a whole new stadium.
        CipherThrowaway 3y ago
        Classic HN conversation here. "The web is too complex! All these web frameworks are too complicated!" "Okay, what do you suggest instead?" "I'd just use [completely unmaintainable technology from the 90s that is no longer supported by its vendor]" "Okay, how would you approach [basic feature of the web framework]?" "Stop moving the goalposts!" Come on, you could at least come up with some hand-waving about cache headers and CDNs.
        phist_mcgee 3y ago
        You missed the classic, "I did this back in the 90s using x and it was more powerful and sane compared to any of this new malarkey"

tacker2000 3y ago

You can generate a swagger-ui doc page from an open api yaml spec by just mounting the file in their swaggerapi/swagger-ui docker container. Same with Redocly. Granted the pages probably wont look as good as what they have here or be integrated in their larger docs, but yea its possible.

CipherThrowaway 3y ago
To me, that is a separate level of decision. Sure, you could avoid the whole problem of building a docs generator by using an off-the-shelf docs generator, and letting the Redoc and Swagger dev teams deal with all the development complexity. But if you are going to build your own docs generator, React and Next with RSC aren't a bad choice. Web development just isn't as simplistic as people on HN seem to think it is.
- Draiken 3y ago
  I agreed with most of your comment but this almost triggered me: > React and Next with RSC aren't a bad choice. Web development just isn't as simplistic as people on HN seem to think it is. Yes it fucking is. I've been doing it for 15+ years and most of the complexity added since about 10 years ago is not required. Many times they're actually regressions. The web is complex because we made it so. This is a perfect example where they could write their own docs generator with MUCH less complexity. You read a damn json/yaml file and make HTML out of it. Style it with CSS and you're finished. It's as maintainable as it gets. Now let's look at running `yarn install` in this project a year from now and see how easy it's going to be to maintain it. Odds are NextJS will be 5 versions behind and with 500 vulnerabilities found in the dependency graph.
  - tacker2000 3y ago
    You are of course right. But probably they got VC cash and some guy said, do it in React bla bla whatever the cost…