From d5d04ae75f37d9a88fd986fdd3e5104856c60405 Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Mon, 11 Sep 2023 15:46:14 +0200 Subject: [PATCH] [docs] Improve npm experience (#38906) Signed-off-by: Olivier Tassinari Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> --- README.md | 102 +++++++++--------------- packages/mui-base/README.md | 40 +++++++++- packages/mui-icons-material/README.md | 6 +- packages/mui-joy/README.md | 42 +++++++++- packages/mui-lab/README.md | 2 +- packages/mui-material/README.md | 44 +++++++++- packages/mui-styled-engine-sc/README.md | 2 +- packages/mui-styled-engine/README.md | 2 +- packages/mui-styles/README.md | 2 +- packages/mui-system/README.md | 4 +- scripts/copyFiles.mjs | 10 +-- 11 files changed, 167 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index cf1f22cf102887..2fea4bc287bde6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

- MUI Core logo + MUI Core logo

MUI Core

@@ -31,15 +31,11 @@ -## Installation +## Documentation ### Material UI -Material UI is available as an [npm package](https://www.npmjs.com/package/@mui/material). - -```bash -npm install @mui/material @emotion/react @emotion/styled -``` +Visit [https://mui.com/material-ui/](https://mui.com/material-ui/) to view the full documentation.
Older versions @@ -53,32 +49,23 @@ npm install @mui/material @emotion/react @emotion/styled **Note:** `@next` only points to pre-releases. Use `@latest` for the latest stable release. -### Base UI - -Base UI is available as an [npm package](https://www.npmjs.com/package/@mui/base). +### Joy UI -```bash -npm install @mui/base -``` +Visit [https://mui.com/joy-ui/getting-started/](https://mui.com/joy-ui/getting-started/) to view the full documentation. -**Note**: Base UI is still in beta. +**Note**: Joy UI is still in beta. We are adding new components regularly and you're welcome to contribute! -### MUI System - -MUI System is available as an [npm package](https://www.npmjs.com/package/@mui/system). +### Base UI -```bash -npm install @mui/system @emotion/react @emotion/styled -``` +Visit [https://mui.com/base-ui/](https://mui.com/base-ui/) to view the full documentation. -Or if you want to use styled-components as the styling engine: +**Note**: Base UI is still in beta. +We are adding new components regularly and you're welcome to contribute! -```bash -npm install @mui/material @mui/styled-engine-sc styled-components -``` +### MUI System -Visit our [styled-components guide](https://mui.com/material-ui/guides/styled-components/) for more information on configuration. +Visit [https://mui.com/system/](https://mui.com/system/) to view the full documentation. ## Sponsors @@ -112,42 +99,15 @@ Gold Sponsors are those who have pledged \$500/month or more to MUI. See the full list of [our backers](https://mui.com/material-ui/discover-more/backers/). -## Getting started with Material UI - -Here is an example of a basic app using Material UI's `Button` component: - -```jsx -import * as React from 'react'; -import Button from '@mui/material/Button'; - -function App() { - return ; -} -``` - -In the interactive demo below, try changing the code and see how it affects the output. -(Hint: change `variant` to `"outlined"` and `color` to `"secondary"`. -For more options, see the [`Button` component page](https://mui.com/material-ui/react-button/) in our docs.) - -[![Edit Button](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/material-ui-u9sy1h) - ## Questions -For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/material-ui) instead of GitHub issues. -Use the "mui" tag on Stack Overflow to make it easier for the community to find your question. +For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/) instead of GitHub issues. ## Examples -Our documentation features [a collection of example projects using Material UI](https://mui.com/material-ui/getting-started/example-projects/). +Our documentation features [a collection of example projects](https://github.com/mui/material-ui/tree/master/examples). -## Documentation - -- [Material UI](https://mui.com/material-ui) -- [Joy UI](https://mui.com/joy-ui/getting-started/) -- [Base UI](https://mui.com/base-ui/) -- [MUI System](https://mui.com/system/getting-started/) - -## Premium themes +## Premium templates You can find complete templates and themes in the [MUI Store](https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=readme-store). @@ -179,30 +139,42 @@ For details of supported versions and contact details for reporting security iss These great services sponsor MUI's core infrastructure: +
- - - GitHub logo + + + GitHub logo [GitHub](https://github.com/) lets us host the Git repository and coordinate contributions. +
+ +
- - - Netlify logo + + + Netlify logo [Netlify](https://www.netlify.com/) lets us distribute the documentation. +
+ +
- - - BrowserStack logo + + + BrowserStack logo [BrowserStack](https://www.browserstack.com/) lets us test in real browsers. -CodeCov logo +
+ +
+CodeCov logo [CodeCov](https://about.codecov.io/) lets us monitor test coverage. + +
diff --git a/packages/mui-base/README.md b/packages/mui-base/README.md index b3c424648eabb1..5c85f93baa5a56 100644 --- a/packages/mui-base/README.md +++ b/packages/mui-base/README.md @@ -1,4 +1,9 @@ -# Base UI + +

+ Base UI logo +

+ +

Base UI

Base UI is a library of unstyled React UI components and hooks. With Base UI, you gain complete control over your app's CSS and accessibility features. @@ -14,8 +19,37 @@ npm install @mui/base -[The documentation](https://mui.com/base-ui/) +Visit [https://mui.com/base-ui/](https://mui.com/base-ui/) to view the full documentation. + +## Questions + +For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/base-ui) instead of GitHub issues. +Use the "base-ui" tag on Stack Overflow to make it easier for the community to find your question. + +## Examples + +Our documentation features [a collection of example projects using Base UI](https://github.com/mui/material-ui/tree/master/examples). ## Contributing -See [the contributing guide](./CONTRIBUTING.md) if you wish to implement Base UI components or hooks. +Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes. + +Contributing to Base UI is about more than just issues and pull requests! +There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base. + +## Changelog + +The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release. + +## Roadmap + +Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/). + +## License + +This project is licensed under the terms of the +[MIT license](/LICENSE). + +## Security + +For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy). diff --git a/packages/mui-icons-material/README.md b/packages/mui-icons-material/README.md index 432e5163d6080c..21988a3f87dbe6 100644 --- a/packages/mui-icons-material/README.md +++ b/packages/mui-icons-material/README.md @@ -26,8 +26,8 @@ npm install @mui/material -- [The documentation](https://mui.com/material-ui/icons/#svgicon) -- [The icons search](https://mui.com/material-ui/material-icons/) +- [The SvgIcon documentation](https://mui.com/material-ui/icons/#svgicon) +- [The Material Design icons search](https://mui.com/material-ui/material-icons/) ## Contributing @@ -39,4 +39,4 @@ To synchronize with Material Icons, do the following: 1. Inside this workspace run `yarn src:download` 2. Inside this workspace run `yarn src:icons` 3. Inside the root run `yarn docs:mdicons:synonyms` -4. If the number of icons changed significantly, edit the icons/icons.md and material-icons/material-icons.md under docs/data/material/components and update the numbers. +4. If the number of icons changes significantly, edit the icons/icons.md and material-icons/material-icons.md under docs/data/material/components and update the numbers. diff --git a/packages/mui-joy/README.md b/packages/mui-joy/README.md index 76ecf2944f5e83..7adc2c28a313ab 100644 --- a/packages/mui-joy/README.md +++ b/packages/mui-joy/README.md @@ -1,4 +1,9 @@ -# Joy UI + +

+ Joy UI logo +

+ +

Joy UI

Joy UI is a library of beautifully designed React UI components built to spark joy. @@ -12,4 +17,37 @@ npm install @mui/joy @emotion/react @emotion/styled ## Documentation -[The documentation](https://mui.com/joy-ui/getting-started/) +Visit [https://mui.com/joy-ui/getting-started/](https://mui.com/joy-ui/getting-started/) to view the full documentation. + +## Questions + +For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/joy-ui) instead of GitHub issues. +Use the "joy-ui" tag on Stack Overflow to make it easier for the community to find your question. + +## Examples + +Our documentation features [a collection of example projects using Joy UI](https://github.com/mui/material-ui/tree/master/examples). + +## Contributing + +Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes. + +Contributing to Joy UI is about more than just issues and pull requests! +There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base. + +## Changelog + +The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release. + +## Roadmap + +Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/). + +## License + +This project is licensed under the terms of the +[MIT license](/LICENSE). + +## Security + +For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy). diff --git a/packages/mui-lab/README.md b/packages/mui-lab/README.md index 59b3d9f90539b7..3a38ed547576ff 100644 --- a/packages/mui-lab/README.md +++ b/packages/mui-lab/README.md @@ -25,4 +25,4 @@ npm install @mui/material @emotion/react @emotion/styled -[The documentation](https://mui.com/material-ui/about-the-lab/) +Visit [https://mui.com/material-ui/about-the-lab/](https://mui.com/material-ui/about-the-lab/) to view the full documentation. diff --git a/packages/mui-material/README.md b/packages/mui-material/README.md index 084828a332db61..ebeee870adc942 100644 --- a/packages/mui-material/README.md +++ b/packages/mui-material/README.md @@ -1,4 +1,9 @@ -# Material UI + +

+ Material UI logo +

+ +

Material UI

Material UI is a comprehensive library of components that features our implementation of Google's [Material Design](https://m2.material.io/design/introduction/) system. @@ -7,9 +12,42 @@ Material UI is a comprehensive library of components that features our implement Install the package in your project directory with: ```bash -npm install @mui/material +npm install @mui/material @emotion/react @emotion/styled ``` ## Documentation -[The documentation](https://mui.com/material-ui/) +Visit [https://mui.com/material-ui/](https://mui.com/material-ui/) to view the full documentation. + +## Questions + +For how-to questions that don't involve making changes to the code base, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/material-ui) instead of GitHub issues. +Use the "material-ui" tag on Stack Overflow to make it easier for the community to find your question. + +## Examples + +Our documentation features [a collection of example projects using Material UI](https://mui.com/material-ui/getting-started/example-projects/). + +## Contributing + +Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes. + +Contributing to Material UI is about more than just issues and pull requests! +There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base. + +## Changelog + +The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release. + +## Roadmap + +Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/). + +## License + +This project is licensed under the terms of the +[MIT license](/LICENSE). + +## Security + +For details of supported versions and contact details for reporting security issues, please refer to the [security policy](https://github.com/mui/material-ui/security/policy). diff --git a/packages/mui-styled-engine-sc/README.md b/packages/mui-styled-engine-sc/README.md index 935bc0cad09cba..5e894fd4d42f80 100644 --- a/packages/mui-styled-engine-sc/README.md +++ b/packages/mui-styled-engine-sc/README.md @@ -7,4 +7,4 @@ It's designed for developers who would like to use `styled-components` as the ma -[The documentation](https://mui.com/material-ui/guides/styled-components/) +Visit [https://mui.com/material-ui/guides/styled-components/](https://mui.com/material-ui/guides/styled-components/) to view the full documentation. diff --git a/packages/mui-styled-engine/README.md b/packages/mui-styled-engine/README.md index e9c59aee7f1c7d..083e5a7a20ab3b 100644 --- a/packages/mui-styled-engine/README.md +++ b/packages/mui-styled-engine/README.md @@ -8,4 +8,4 @@ It is used internally in the `@mui/system` package. -[The documentation](https://mui.com/material-ui/guides/styled-components/) +Visit [https://mui.com/material-ui/guides/styled-components/](https://mui.com/material-ui/guides/styled-components/) to view the full documentation. diff --git a/packages/mui-styles/README.md b/packages/mui-styles/README.md index 60738855c6342c..93587d0f4a587a 100644 --- a/packages/mui-styles/README.md +++ b/packages/mui-styles/README.md @@ -12,4 +12,4 @@ npm install @mui/styles ## Documentation -[The documentation](https://mui.com/system/styles/basics/) +Visit [https://mui.com/system/styles/basics/](https://mui.com/system/styles/basics/) to view the full documentation. diff --git a/packages/mui-system/README.md b/packages/mui-system/README.md index 1a1bbc28a8d65f..5f83a2b559a983 100644 --- a/packages/mui-system/README.md +++ b/packages/mui-system/README.md @@ -1,6 +1,6 @@ # MUI System -CSS utilities for rapidly laying out custom designs. +MUI System is a collection of CSS utilities to help you rapidly lay out custom designs. ## Installation @@ -16,4 +16,4 @@ npm install @mui/system @emotion/react @emotion/styled -[The documentation](https://mui.com/system/getting-started/) +Visit [https://mui.com/system/getting-started/](https://mui.com/system/getting-started/) to view the full documentation. diff --git a/scripts/copyFiles.mjs b/scripts/copyFiles.mjs index d2fe97de4cc8fd..6f0ddab28e686e 100644 --- a/scripts/copyFiles.mjs +++ b/scripts/copyFiles.mjs @@ -162,13 +162,9 @@ async function run() { const packageData = await createPackageFile(); await Promise.all( - [ - // use enhanced readme from workspace root for `@mui/material` - packageData.name === '@mui/material' ? '../../README.md' : './README.md', - '../../CHANGELOG.md', - '../../LICENSE', - ...extraFiles, - ].map((file) => includeFileInBuild(file)), + ['./README.md', '../../CHANGELOG.md', '../../LICENSE', ...extraFiles].map((file) => + includeFileInBuild(file), + ), ); await addLicense(packageData);