question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Proposal: Markdown Generation, Types, UI/UX Overhaul

See original GitHub issue

I have a couple different changes I think could benefit this project. Let me know if you would be open to these changes and I’d be happy to do the work of submitting PRs around them.

1. Refactor markdown generation to JSX

Currently the generation of markdown is handled through a custom utility defined in docusaurus-plugin-openapi. The implementation uses these to generate the independent sections, such as: createParamsTable, createStatusCodesTable, etc.

I’d like to propose refactoring these to render with React directly, to eliminate the declarative pattern of:

create("thead", {
  children: create("tr", {
    children: create("th", {
      style: { textAlign: "left" },
      children: `${
        type.charAt(0).toUpperCase() + type.slice(1)
      } Parameters`,
    }),
  }),
}),

and moving to:

return (
  <thead>
    <tr>
      <th style={textAlign: 'left' }>
        {type.chartAt(0).toUpperCase() + type.slice(1)} Parameters
      </th>
    </tr>
  </thead>
);

When docusaurus builds, the SSR behavior will still output the contents as HTML.

The benefits here are:

  1. Removes internal utils for DOM creation
  2. Standardizes on HTML/JSX
  3. Allows for more complex UI implementations that the existing utilities would not easily satisfy

2. Move markdown sections to docusaurus-theme-openapi

By moving the markdown section components (params table, status table, etc.) to the theme and exporting from that library, developers can more easily build custom ApiItem/ApiPage implementations, while reusing more of the internal sections.

For example, in my project I have a custom apiItemComponent defined & then need to manage recreating the UI if I want to customize the ApiContent section. Ideally I could reference all the existing sections and render a custom implementation for a specific section (e.g.: createStatusCodesTable).

3. Expose OpenAPI types

Continuing on the 2nd point, I would like to expose the OpenAPI types declared here: https://github.com/cloud-annotations/docusaurus-openapi/blob/main/packages/docusaurus-plugin-openapi/src/types.ts to the entry point of the module. This would allow custom implementations that are building custom section replacements, to leverage the existing types.

4. UI/UX Overhaul

I am unsure if the current design is based off any thing specific. The project that I am migrating to docusaurus currently is hosted in Readme.io. Their UI design has some nice improvements that I think would enhance this plugin: https://sample-threes.readme.io/reference/authentication-1

If approved, I would like to merge this work into a “next” branch, and split up the individual migrations. We wouldn’t need to match the design 1:1, but there are a few immediate differences that I think would benefit this project:

  • Color coded request methods & combining the request method and server url into a single area Screen Shot 2022-08-24 at 9 04 00 PM

  • Move the inputs for path params/request body in the same area as their API description (also clicking the path parameter focuses the input) Screen Shot 2022-08-24 at 9 04 44 PM

  • Click a response opens a dialog with the shape of the response: Screen Shot 2022-08-24 at 9 05 32 PM

  • Users can click predefined response examples Screen Shot 2022-08-24 at 9 06 12 PM

  • The language options can handle many options, without clipping off the screen. Screen Shot 2022-08-24 at 9 06 41 PM

Issue Analytics

  • State:open
  • Created a year ago
  • Reactions:5
  • Comments:11 (9 by maintainers)

github_iconTop GitHub Comments

3reactions
bourdakos1commented, Sep 2, 2022

A little background, when we first wrote this we used JSX to render everything. However, we ran into a handful of issues with the approach. The way we had it working was to save each piece of openapi content that could be formatted with markdown as a markdown file that Docusaurus would ingest, but this didn’t scale very well, it was a lot of piping and a lot of files generated. What we do now is basically turn a page of the spec into a single markdown file, that’s what the “ApiContent” component is. This approach has been working pretty well so far and has the added benefit of the generated markdown being reusable outside of Docusaurus.

I’ll dig around and see if there were any other big reasons for why we switched to this new markdown generation approach.

I’m happy to switch back to JSX, but I’d like to hear more about your plan first

1reaction
sean-perkinscommented, Sep 2, 2022

That would be awesome, thanks @arrigolupori. I should have a few PRs up by this weekend to tackle the higher level UI refactors. I am going to leave the form control UI alone at first, but will migrate that once the new main container UI is in place.

One thing that I am unaware of how to best solve for, is when moving the rendering into JSX, we lose the ability of rendering the OpenAPI spec information that contains markdown formatted contents. My first PRs will avoid this scenario, as I will still be rendering the <ApiContent /> component: https://github.com/cloud-annotations/docusaurus-openapi/blob/e5c0ec7fafda112cc3c4c297a4ae36e85f8e3552/packages/docusaurus-theme-openapi/src/theme/ApiItem/index.tsx#L38 for most of the sections, but if anyone has ideas let me know 👍

For example, if my OpenAPI endpoint description was:

  description: "This is a description. :::tip Try it out ::: **This should be bolded**"

We want to continue to render that output as formatted markdown & admonitions. We could pass the contents through a plugin like react markdown again, but this will only format standard markdown into HTML. I would assume there is a docusaurus utility or internal function that helps solve for this.

I am unsure why the <ApiContent /> approach does not have this problem and renders the markdown correctly.

Read more comments on GitHub >

github_iconTop Results From Across the Web

Write A UX Proposal: How-To Guide - Usability Geek
This article explains how to write a good UX proposal to bring all ... from tweaking the position of UI elements or an...
Read more >
Daring Fireball
My latest survey indicates that Apple will likely cancel or postpone the mass production plan for the 2024 iPhone SE 4.
Read more >
What Is the UX Design Process? An Actionable Guide for 2023
Then I'll take you through a detailed, step-by-step guide of the UX design process, and propose a few hands-on tasks you can do...
Read more >
what is github reddit
Markdown is a lightweight markup language for creating formatted text using a plain-text editor. ... For simple scripts, you can select a type...
Read more >
Serial no. 5 Set the 'noout' flag. recent car accidents new york ...
Domino, Emma Frost, Goldpool, Night With this Marvel Contest of Champions (MCOC) Tier List I'm trying to cover a few types of players,...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found