[blog] Share what's changed about the new docs structure

docs/lib/sourcing.ts

@@ -32,7 +32,7 @@ export const getBlogPost = (filePath: string): BlogPost => {
 
 // Avoid typos in the blog markdown pages.
 // https://www.notion.so/mui-org/Blog-247ec2bff5fa46e799ef06a693c94917
-const ALLOWED_TAGS = ['MUI Core', 'MUI X', 'News', 'Company', 'Developer survey'];
+const ALLOWED_TAGS = ['MUI Core', 'MUI X', 'News', 'Company', 'Developer survey', 'Product'];
 
 export const getAllBlogPosts = () => {
   const filePaths = getBlogFilePaths();

docs/pages/blog/docs-updates.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import TopLayoutBlog from 'docs/src/modules/components/TopLayoutBlog';
+import { docs } from './docs-updates.md?@mui/markdown';
+
+export default function Page() {
+  return <TopLayoutBlog docs={docs} />;
+}

docs/pages/blog/docs-updates.md

@@ -0,0 +1,66 @@
+---
+title: 'Our docs just got a major upgrade—here's what that means for you'
+description: Each of MUI's products now has its own dedicated documentation, making it easier than ever to find exactly what you need.
+date: 2022-04-06T00:00:00.000Z
+authors: ['danilo-leal']
+tags: ['News', 'Product']
+---
+
+As MUI continues to grow beyond our flagship product, Material UI (we [rebranded the company](/blog/material-ui-is-now-mui/) last year as a first step), it has become clear that the documentation for our products can no longer all live under one roof.
+
+That's why we're excited to announce that we are shipping a major upgrade to our documentation, to make it easier than ever to find exactly what you need—no matter which MUI products you're working with.
+
+## Wait... what MUI products are you talking about?
+
+We currently offer two main product lines:
+
+- **MUI Core**—a collection of foundational component libraries, including:
+  - _Material UI_ —components that implement Google's Material Design
+  - _MUI Base_ —unstyled components for implementing your own design system
+  - _MUI System_ —CSS utilities for quickly laying out design systems
+- **MUI X**—a collection of advanced components for complex use cases, including:
+  - _Data Grid_ —fast, feature-rich, extendable React data table
+  - _Date and Time Pickers_ —interface control components for selecting dates and times
+
+## What has changed?
+
+All MUI products still live under the [mui.com](http://mui.com) domain, but each of them now has its own respective URL and documentation.
+We added an identifier and menu to the upper-left corner of the docs for improved navigation:
+
+<img src="/static/blog/docs-updates/docs-separation.png" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" alt="Screenshot of the product identifier menu" />
+
+As for the URLs, this is how they look now:
+
+- MUI Core:
+  - Material UI: [https://mui.com/material-ui/](https://mui.com/material-ui/getting-started/installation/)
+  - MUI Base: [https://mui.com/base/](https://mui.com/base/getting-started/installation/)
+  - MUI System: [https://mui.com/system/](https://mui.com/system/basics/)
+- MUI X:
+  - Data Grid: [https://mui.com/x/react-data-grid/](https://mui.com/x/react-data-grid/)
+  - Date and Time Pickers: [https://mui.com/x/react-date-pickers/](https://mui.com/x/react-date-pickers/getting-started/)
+
+> 📖 The date and time pickers have been promoted from the lab (`@mui/lab`) to MUI X—still available under the MIT license. To learn more, check out the [blog post about the newest MUI X components](/blog/lab-date-pickers-to-mui-x/).
+
+### Improved search experience
+
+The documentation restructuring ranks search results based on the product that you are currently looking at.
+For example, if you are looking at Material UI documentation, when you press <kbd><kbd class="key">⌘</kbd>+<kbd class="key">K</kbd></kbd> (or <kbd><kbd class="key">CTRL</kbd>+<kbd class="key">K</kbd></kbd> on Windows) and type a keyword, you will find that most of the results are related to Material UI.
+
+We have also added product labels for Material UI and MUI Base in case it's unclear which library the search results refer to.
+
+<img src="/static/blog/docs-updates/docs-product-label.png" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" alt="Screenshot of the search results displaying product labels per result" />
+
+As a side benefit of the documentation restructuring, we have seen a huge improvement in the quality of search results related to MUI X. Data Grid users can now see comprehensive results when searching for features. Here is a comparison of before and after when searching for the "pagination" feature:
+
+<img src="/static/blog/docs-updates/docs-search-comparison.png" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" alt="Screenshots of the docs before and after comparing Data Grid search results" />
+
+## Moving forward
+
+This separation will become increasingly beneficial as each product grows, such as additional components in MUI X and MUI Base.
+
+As we move forward working on [our second design system package](https://deploy-preview-30686--material-ui.netlify.app/experiments/), the separation will make it possible for us to build the documentation for each system using its default styles—so the docs themselves will serve as examples of their corresponding component libraries.
+
+If you have any feedback or suggestions, we definitely want to hear from you.
+Please open an issue in the [mui/material-ui repository on GitHub](https://github.com/mui/material-ui/issues), and be sure to start the **Title** with [docs].
+
+Happy developing! 👩‍💻

docs/pages/blog/lab-date-pickers-to-mui-x.md

@@ -14,13 +14,17 @@ This means we'll be dedicating even more time and effort to these complex compon
 
 Date and time pickers are interface controls that enable the user to select a date (or time) from a menu.
 
+<img src="/static/blog/lab-date-pickers-to-mui-x/date-time-picker.png" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" alt="Date and time picker component" />
+
+<p class="blog-description">Date and time pickers using the default Material UI design</p>
+
 Common design patterns include text inputs, dropdown lists, calendars, timelines, and scrolling pickers on mobile devices.
 
 The user may need to select an individual date/time, or a range.
 
 ## What is MUI X?
 
-MUI X is a collection of advanced components built for complex use cases.
+[MUI X](/x/) is a collection of advanced components built for complex use cases.
 
 As opposed to the Core library, which leans on the open-source community for support, MUI X components require several full-time developers dedicated to engineering and ongoing maintenance.
 

docs/pages/blog/material-ui-is-now-mui.md

@@ -7,7 +7,7 @@ tags: ['Company']
 card: true
 ---
 
-<img src="/static/blog/material-ui-is-now-mui/intro.png" alt="The new MUI logo" style="width: 100%; margin-bottom: 16px;" />
+<img src="/static/blog/material-ui-is-now-mui/intro.png" alt="The new MUI logo" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" />
 
 Starting today we are evolving our brand identity to clarifying the difference between our company and our products.
 
@@ -43,13 +43,10 @@ Our primary focus was to revamp the **customization Developer Experience (DX)**.
 It had become clear that design (aesthetic, UX) and DX were key to unlocking the next stage of growth.
 
 The new brand supports the [v5.0.0 release](/blog/mui-core-v5/) while also creating space for new initiatives that broaden the company horizon. It's a big deal!
-
 Our ultimate goal is to become the most effective and efficient tool to build UIs while making it accessible to the many.
 
 ## Our new brand
 
-Let's dig in.
-
 ### A new name
 
 We are breaking the strong association with Material Design
@@ -74,11 +71,11 @@ It's basically the same, to keep it familiar –
 we're keeping the geometrical shape, to resonate with the _building blocks_ idea of the components –
 however, we're reducing the emphasis on the 3D perspective, stepping away from the notion of elevation that Material Design coined.
 
-<img loading="lazy" src="/static/blog/material-ui-is-now-mui/old-new.png" alt="Side-by-side of the new and old logo" style="width: 612px; margin-bottom: 16px;" />
+<img loading="lazy" src="/static/blog/material-ui-is-now-mui/old-new.png" alt="Side-by-side of the new and old logo" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" />
 
 To better identify, market, and promote each product, we're introducing logos for each one of them.
 
-<img loading="lazy" src="/static/blog/material-ui-is-now-mui/products.png" alt="Logos for MUI Core, MUI X and Templates" style="width: 600px; margin-bottom: 16px;" />
+<img loading="lazy" src="/static/blog/material-ui-is-now-mui/products.png" alt="Logos for MUI Core, MUI X and Templates" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" />
 
 - **MUI Core** contains ready-to-use foundational components, free forever.
 - **MUI X** includes advanced and powerful components for complex use-cases.
@@ -92,18 +89,12 @@ The npm organization name (scope) has moved from @material-ui to [@mui](https://
 
 ### A new website & documentation
 
-Lastly, to celebrate the start of a new chapter for the company with the release of v5.0.0, and new products in the making, we're introducing a brand new website and documentation design.
-
-You'll find a completely different theme from Material Design – new typeface, colors, box-shadows, and more,
-all done using the flexible theming features of v5.
-
-<img loading="lazy" src="/static/blog/material-ui-is-now-mui/palette.png" alt="Selection of the new color palette and gradients" style="width: 600px; margin-bottom: 16px;" />
-
-<p class="blog-description">The color palette of our brand.</p>
+Lastly, to celebrate the start of a new chapter for the company with the release of v5.0.0, and new products in the making, we're introducing a brand new website and documentation design. You'll find a completely different theme from Material Design – new typeface, colors, box-shadows, and more,
+all done using the flexible theming features of v5. [Head to the new website](/)!
 
-[Head to the new website](/).
+<img loading="lazy" src="/static/blog/material-ui-is-now-mui/website-homepage.png" alt="Screenshot of the new website homepage" style="width: 796px; margin-top: 16px; margin-bottom: 16px;" />
 
-> Note that these changes do **not** impact the design of the components released under the `@mui/*` npm packages.
+> 💡 Note that these changes in the website and documentation do **not** impact the design of the components released under the `@mui/*` npm packages.
 
 ## The path ahead
 

docs/src/modules/components/MarkdownElement.js

@@ -254,22 +254,19 @@ const Root = styled('div')(({ theme }) => ({
     backgroundColor: theme.palette.divider,
   },
   '& kbd.key': {
-    // Style taken from GitHub
-    padding: '4px 5px',
+    padding: '5px',
     display: 'inline-block',
     whiteSpace: 'nowrap',
     margin: '0 1px',
-    font: '11px SFMono-Regular,Consolas,Liberation Mono,Menlo,monospace',
+    font: '11px Consolas,Liberation Mono,Menlo,monospace',
     lineHeight: '10px',
     color: theme.palette.text.primary,
     verticalAlign: 'middle',
-    backgroundColor: theme.palette.mode === 'dark' ? 'transparent' : theme.palette.grey[50],
-    border: `1px solid ${
-      theme.palette.mode === 'dark' ? theme.palette.grey[800] : theme.palette.grey[300]
-    }`,
+    backgroundColor: theme.palette.mode === 'dark' ? blueDark[900] : theme.palette.grey[50],
+    border: `1px solid ${theme.palette.mode === 'dark' ? blueDark[500] : theme.palette.grey[300]}`,
     borderRadius: 5,
     boxShadow: `inset 0 -1px 0 ${
-      theme.palette.mode === 'dark' ? theme.palette.grey[800] : theme.palette.grey[300]
+      theme.palette.mode === 'dark' ? blueDark[700] : theme.palette.grey[300]
     }`,
   },
   '& details': {