[docs] Add installation component #36766

siriwatknp · 2023-04-03T09:49:44Z

After seeing the installation section (with pnpm added`) in #36650 and https://deploy-preview-36717--material-ui.netlify.app/base/getting-started/quickstart/#installation, I cannot tolerate anymore 🤣.

This PR adds Installation component that renders Tabs. Here is what it looks like:

It store the latest value that you select in the local storage, so that the next time you open the page it focuses on that tab. (however, the UX is not great because the content swap after mounted. Feedbacks welcome)

Let's you specify dep managers for each page

{{"component": "components/markdown/Installation", "dep": "@mui/base", "managers": ["yarn", "npm", "pnpm"]}}

Note: At first, I wanted to extend the markdown to enable us to write some syntax that will generate Tabs but I could not find a good reference because GMF (Github markdown format) does not support tabs. The closest one is Rmarkdown but it looks really complicated to implement.

Todos

Make it works for the X team https://mui.com/x/react-date-pickers/getting-started/
Apply every where in the core docs

Preview: https://deploy-preview-36766--material-ui.netlify.app/experiments/docs/installation/

mui-bot · 2023-04-03T09:52:27Z

Netlify deploy preview

docs/data/base/getting-started/installation/installation.md

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against 098fd4a

danilo-leal · 2023-04-03T12:58:59Z

Very excited that we're working on this! At first, I'd suggest something within the markdown, but it's cool that you've explored that already. As far as the design goes, though, I imagined the tabs to be integrated into the code block, not an individual tab element on the page body (especially now that we're adding tabs to the high-level page navigation). I'd also like to see if there's a way to generalize this component more instead of something targeted at installation commands. We may want to use tabs within the code block for other stuff.

Additionally, I'm curious if we could also experiment with ways to display the file's name within the code block either ⎯ like we did on Joy's theme builder page. It would be visually very similar to the tabs, and it could even have a tab (exactly like Joy's example).

siriwatknp · 2023-04-04T10:48:44Z

@flaviendelangle I thinking about this syntax to make it works with DatePickers:

{{"component": "components/markdown/Installation", "installation": "%Plan %DateLibrary", "managers": ["yarn", "npm"], "Plan": [["Community", "@mui/x-date-pickers"], ["Pro", "@mui/x-date-pickers-pro"]], "DateLibrary": ["dayjs", "date-fns", "luxon", "moment"]}}

Do you get it at first glance 🤔?

Note: at first I'd like to use {{Plan}} {{DateLibary}} as a template but the markdown parser does not work with this so I have to go with %Plan %DateLibrary.

siriwatknp · 2023-04-04T11:24:28Z

@danilo-leal updated to

flaviendelangle · 2023-04-06T06:10:39Z

@siriwatknp I'm fine with this synthax
I'd be curious to see the resulting UI 👍

…/installation-tabs

siriwatknp · 2023-04-07T07:37:51Z

@flaviendelangle How about this?

cc @danilo-leal

flaviendelangle · 2023-04-07T08:26:49Z

cc @alexfauquette @LukasTy

For me we also need to be able to clean the label ("DateLibrary" is not great without a space).

LukasTy · 2023-04-07T08:35:20Z

For me we also need to be able to clean the label ("DateLibrary" is not great without a space).

Agreed, IMHO, a bit of spacing between the label and toggle button group wouldn't hurt, but other than that it looks great. 👍

alexfauquette · 2023-04-07T09:10:59Z

docs/src/components/markdown/Installation.tsx

+            <HighlightedCode
+              language="bash"
+              code={`${
+                { yarn: 'yarn add', npm: 'npm install', pnpm: 'pnpm add' }[item]
+              } ${finalInstallation}`}
+            />


Probably too complicated, but would it be possible to split this into two distinct components:

HighlightedCodeWithSelect similar to HighlightedCode but accepts a callback for code with the selected state

Installation That reuses the previous one to do what you're currently doing.

The example I've in mind is the pickers setups. It is not at all about npm or yarn but has 2 selects to adapt the code. In such a case, we could reuse the HighlightedCodeWithSelect to get an up-to-date UI

👍 I will take a look at it.

alexfauquette · 2023-04-07T09:11:03Z

packages/markdown/parseMarkdown.js

+          name: 'tabs',
+          level: 'block',
+          start(src) {
+            const match = src.match(/===/);


Not sure to understand. You plan to add the possibility to write the following markdown, but I do not see how it should be used

=== Some content ===

Sorry, this should be reverted.

oliviertassinari · 2023-04-09T15:53:53Z

docs/pages/experiments/docs/installation.md

+
+## Basic
+
+{{"component": "components/markdown/Installation", "installation": "@mui/material @emotion/react @emotion/styled"}}


This PR is interesting, and much better than 3 headers for npm, yarn, pnpm. Now, I would like to bring some light on the level of abstraction, figuring out where is the right balance:

Update

Should this cover npm updates: https://mui.com/material-ui/migration/migration-v4/#update-react too? Maybe it needs to be a bit higher level?

More generic?

We could consider a higher-level API, this would allow to support any type of bash actions:

Suggested change

{{"component": "components/markdown/Installation", "installation": "@mui/material @emotion/react @emotion/styled"}}

{{"component": "components/markdown/TabsBash", "tabs": ["npm", "yarn", "pnpm"], "npm": "npm install @mui/material @emotion/react @emotion/styled", "yarn add @mui/material @emotion/react @emotion/styled", pnpm: "pnpm add @mui/material @emotion/react @emotion/styled" }}

CodeGroup?

But then maybe it's the notion of code group that we need, tabs between any time of code blocks.

https://mintlify.com/docs/content/components/code-group

https://tailwindcss.com/docs/plugins and the source

Tabs?

I have seen even higher-level APIs, aTabs API:

https://nextra.site/docs/docs-theme/built-ins/tabs.

https://mintlify.com/docs/components/tabs#tab-props

https://docusaurus.io/docs/markdown-features/tabs

Stripe, I don't quite understand how they manage it. It seems to be API based: https://stripe.com/docs/invoicing/overview#paid

Then people add a code block inside each tab. This feels a bit cheap, two examples that don't feel so great: https://docusaurus.io/docs/installation#build, https://stripe.com/docs/stripe-js/react#setup

Thanks for sharing. The ideal result looks like the code group from Mintlify.

samuelsycamore · 2023-06-14T16:51:06Z

Can we move forward with this? I like the idea of a higher-level API for this component but in the meantime I'd love to see this implemented in the docs sooner rather than later.

alexfauquette · 2023-06-14T20:42:01Z

I'd love to see this implemented in the docs sooner rather than later.

If something is not well done at the first shot in the docs, it ends up there for a long time before someone finds the motivation/time to fix it.

@siriwatknp would you need some help on this PR? This week I might be busy but after the alpha release, I should get a bit more bandwidth

siriwatknp · 2023-06-15T04:11:46Z

I'd love to see this implemented in the docs sooner rather than later.

If something is not well done at the first shot in the docs, it ends up there for a long time before someone finds the motivation/time to fix it.

@siriwatknp would you need some help on this PR? This week I might be busy but after the alpha release, I should get a bit more bandwidth

Definitely @alexfauquette, thanks for the help!.

alexfauquette · 2023-07-11T13:45:33Z

I'm closing it since the codeblock is now available on docs and the remaining interaction will be added in the X repo:

mui/mui-x#9644

add installation component

4f2caae

siriwatknp added docs Improvements or additions to the documentation scope: docs-infra Specific to the docs-infra product labels Apr 3, 2023

siriwatknp added 3 commits April 4, 2023 15:40

wip: use base Tabs

765d9da

add styles

60fc072

improve SSR styles

c6b8595

tiny design tweaks

d56ee31

mj12albert mentioned this pull request Apr 6, 2023

[base][docs] Base UI Quickstart Guide #36717

Merged

1 task

siriwatknp added 2 commits April 7, 2023 11:41

Merge branch 'master' of https://github.com/mui/material-ui into docs…

74f77b7

…/installation-tabs

add multiple options

098fd4a

alexfauquette reviewed Apr 7, 2023

View reviewed changes

oliviertassinari reviewed Apr 9, 2023

View reviewed changes

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label May 1, 2023

mj12albert mentioned this pull request May 11, 2023

[docs][base-ui] Add plain CSS, MUI System, Tailwind CSS and non-styled option for the Introduction demos #37222

Closed

17 tasks

flaviendelangle mentioned this pull request May 17, 2023

[docs] Add npm/yarn tabs to installation pages. mui/mui-x#5272

Closed

2 tasks

alexfauquette mentioned this pull request Jun 19, 2023

[docs-infra] Allows to use codeblock in the docs #37643

Merged

alexfauquette mentioned this pull request Jul 11, 2023

[docs] Improve the UI for pickers introduction mui/mui-x#9644

Merged

alexfauquette closed this Jul 11, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add installation component #36766

[docs] Add installation component #36766

siriwatknp commented Apr 3, 2023 •

edited by oliviertassinari

Loading

mui-bot commented Apr 3, 2023 •

edited

Loading

danilo-leal commented Apr 3, 2023

siriwatknp commented Apr 4, 2023 •

edited

Loading

siriwatknp commented Apr 4, 2023

flaviendelangle commented Apr 6, 2023

siriwatknp commented Apr 7, 2023

flaviendelangle commented Apr 7, 2023

LukasTy commented Apr 7, 2023

alexfauquette Apr 7, 2023

siriwatknp Apr 7, 2023

alexfauquette Apr 7, 2023

siriwatknp Apr 7, 2023

oliviertassinari Apr 9, 2023 •

edited

Loading

siriwatknp Apr 10, 2023

samuelsycamore commented Jun 14, 2023

alexfauquette commented Jun 14, 2023

siriwatknp commented Jun 15, 2023

alexfauquette commented Jul 11, 2023


		## Basic

		{{"component": "components/markdown/Installation", "installation": "@mui/material @emotion/react @emotion/styled"}}

	{{"component": "components/markdown/Installation", "installation": "@mui/material @emotion/react @emotion/styled"}}
	{{"component": "components/markdown/TabsBash", "tabs": ["npm", "yarn", "pnpm"], "npm": "npm install @mui/material @emotion/react @emotion/styled", "yarn add @mui/material @emotion/react @emotion/styled", pnpm: "pnpm add @mui/material @emotion/react @emotion/styled" }}

[docs] Add installation component #36766

[docs] Add installation component #36766

Conversation

siriwatknp commented Apr 3, 2023 • edited by oliviertassinari Loading

Todos

mui-bot commented Apr 3, 2023 • edited Loading

Netlify deploy preview

Bundle size report

danilo-leal commented Apr 3, 2023

siriwatknp commented Apr 4, 2023 • edited Loading

siriwatknp commented Apr 4, 2023

flaviendelangle commented Apr 6, 2023

siriwatknp commented Apr 7, 2023

flaviendelangle commented Apr 7, 2023

LukasTy commented Apr 7, 2023

alexfauquette Apr 7, 2023

Choose a reason for hiding this comment

siriwatknp Apr 7, 2023

Choose a reason for hiding this comment

alexfauquette Apr 7, 2023

Choose a reason for hiding this comment

siriwatknp Apr 7, 2023

Choose a reason for hiding this comment

oliviertassinari Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

Update

More generic?

CodeGroup?

Tabs?

siriwatknp Apr 10, 2023

Choose a reason for hiding this comment

samuelsycamore commented Jun 14, 2023

alexfauquette commented Jun 14, 2023

siriwatknp commented Jun 15, 2023

alexfauquette commented Jul 11, 2023

siriwatknp commented Apr 3, 2023 •

edited by oliviertassinari

Loading

mui-bot commented Apr 3, 2023 •

edited

Loading

siriwatknp commented Apr 4, 2023 •

edited

Loading

oliviertassinari Apr 9, 2023 •

edited

Loading