docs: refactor API documentation

[Josh-Cena]

Motivation

While working on the documentation, I found that the API documentation is quite hard to follow with a giant code block. This PR attempts to use tables consistently for all API.

As I continued working on the refactoring, I realized that this will also resolve #3643.

Have you read the Contributing Guidelines on pull requests?

Yes

Test plan

Changes include:

• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/sidebar#sidebar-item-category
• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/blog
• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/api/plugins/@docusaurus/plugin-content-docs
• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/api/plugins/@docusaurus/plugin-content-blog
• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/api/plugins/@docusaurus/plugin-content-pages
• https://deploy-preview-5219--docusaurus-2.netlify.app/docs/next/api/themes/configuration

Related PRs

Initially documentation for #5203, but when I merged this branch I found some docs already written 😂 Anyways I also enhanced related docs

[netlify]

✔️ [V2]

🔨 Explore the source changes: 50a24d4

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/610aa1fe11e88600089654d8

😎 Browse the preview: https://deploy-preview-5219--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	32
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5219--docusaurus-2.netlify.app/

[lex111]

Nice improvement! However I would fix the following ones:

• Element table not allowed as child of element small in this context. And in general it makes little sense to reduce font size in table at all.
• It is also better to move Default column right after Type. Many docs follow exactly this ordering of columns in similar tables (name | type | default | description).

[Josh-Cena]

• Element table not allowed as child of element small in this context. And in general it makes little sense to reduce font size in table at all.

Agree that it looks awkward, but using regular font would over-compress the column width of the "description" field and make the layout even more awkward... The other doc sites I've seen use a smaller font size (Ant Design, Vuetify, etc.). Should I use styling instead?

• It is also better to move Default column right after Type. Many docs follow exactly this ordering of columns in similar tables (name | type | default | description).

Absolutely, makes sense

[lex111]

Yes, but small font is uncomfortable to read, so it's better use regular font size. Let's wait for opinion from @slorber then.

[Josh-Cena]

Need some help here, I don't really understand the difference between DocPage and DocItem even after reading the code

[slorber]

DocPage is more like the comp responsible for handling the routing and layout inside a doc version.

Keep descriptions as is, I'll try to figure out how to organize this better later and try to rename those comps

[slorber]

Thanks, that's a good improvement and will also fix some searchability issues due to having options only documented in code blocks!

Yes, but small font is uncomfortable to read, so it's better use regular font size. Let's wait for opinion from @slorber then.

Small looks better to me, but I understand why it can be an a11y concern. At the same time it remains big enough and users can still use their browser zoom? Not using small will penalize all users with a less readable layout so I'd suggest to keep small

Will try to review this in depth later

[slorber]

looks good, thanks 👍 and it solves some searcheability issues we have with algolia + codeblocks.

Going to merge. Open to refine the table/small thing is someone has something better to suggest.

It is also possible that this small HTML item can mess up with Crowdin docs translations: we'll see after merging.

[Josh-Cena]

It seems to me that adding a module css may not be a bad choice, but we can wait and see since the current solution has less code

[slorber]

It seems to me that adding a module css may not be a bad choice, but we can wait and see since the current solution has less code

I don't understand what you mean 😅

[Josh-Cena]

I mean, adding an api.module.css with:

.apiTable {
  font-size: 10px;
}

And then apply this class to every table that we wrap with <small />

[slorber]

Having an <ApiTable> mdx component could work instead of wrapping with <small>

If possible I'd prefer to use simple markup without React props because it tends to mess-up a bit with Crowdin without using ```mdx-code-block escaping