Addon-docs: CSS classes for escape-hatch theming wrapper/content (#8061)

Addon-docs: CSS classes for escape-hatch theming wrapper/content

addons/docs/README.md

@@ -209,7 +209,8 @@ Install the preset with care. If you've already configured Typescript manually,
 
 Want to learn more? Here are some more articles on Storybook Docs:
 
-- References: [DocsPage](./docs/docspage.md) / [MDX](./docs/mdx.md) / [FAQ](./docs/faq.md) / [Recipes](./docs/recipes.md)
+- References: [DocsPage](./docs/docspage.md) / [MDX](./docs/mdx.md) / [FAQ](./docs/faq.md) / [Recipes](./docs/recipes.md) / [Theming](./docs/theming.md)
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
 - [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/docs/docspage.md

@@ -32,7 +32,7 @@ However, `DocsPage` brings the following improvements:
 
 Storybook uses `component` to extract the component's description and props, and will rely on it further in future releases. We encourage you to add it to existing stories and use it in all new stories.
 
-Here's how to set the component in [Component Story Format (CSF)]():
+Here's how to set the component in [Component Story Format (CSF)](https://storybook.js.org/docs/formats/component-story-format/):
 
 ```js
 import { Badge } from './Badge';
@@ -241,7 +241,8 @@ The docs preset assumes this naming convention for its `source-loader` setup. If
 
 Want to learn more? Here are some more articles on Storybook Docs:
 
-- References: [README](../README.md) / [MDX](./mdx.md) / [FAQ](./faq.md) / [Recipes](recipes.md)
+- References: [README](../README.md) / [MDX](mdx.md) / [FAQ](faq.md) / [Recipes](recipes.md) / [Theming](theming.md)
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
 - [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/docs/faq.md

@@ -46,7 +46,8 @@ This is just [Component Story Format (CSF)](https://medium.com/storybookjs/compo
 
 Want to learn more? Here are some more articles on Storybook Docs:
 
-- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [Recipes](recipes.md)
+- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [Recipes](recipes.md) / [Theming](theming.md)
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
 - [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/docs/mdx.md

@@ -198,7 +198,8 @@ Be sure to update your Storybook config file to load `.stories.mdx` stories, as
 
 `MDX` is an experimental feature and there's a lot more that hasn't been documented yet. Here are some more articles on Storybook Docs that contain more information:
 
-- References: [README](../README.md) / [DocsPage](docspage.md) / [FAQ](faq.md) / [Recipes](recipes.md)
+- References: [README](../README.md) / [DocsPage](docspage.md) / [FAQ](faq.md) / [Recipes](recipes.md) / [Theming](theming.md)
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
 - [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/docs/recipes.md

@@ -132,7 +132,8 @@ yarn build-storybook --docs
 
 Want to learn more? Here are some more articles on Storybook Docs:
 
-- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [FAQ](faq.md)
+- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [FAQ](faq.md) / [Theming](theming.md)
 - Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
 - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
 - [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/docs/theming.md

@@ -0,0 +1,71 @@
+# Storybook Docs Theming
+
+[Storybook Docs](../README.md) is themable! There are three different levels of theming, just to keep things interesting:
+
+- [Storybook theming](#storybook-theming)
+- [CSS escape hatches](#css-escape-hatches)
+- [MDX component overrides](#mdx-component-overrides)
+
+## Storybook theming
+
+Storybook theming is the **recommended way** to theme your docs. If you update your storybook theme according to [the documentation](https://storybook.js.org/docs/configurations/theming/), Storybook Docs should adapt in reasonable ways.
+
+For example, here's how to change your docs (and Storybook) to the dark theme, by modifying `.storybook/config.js`:
+
+```js
+import { addParameters } from '@storybook/react';
+import { themes } from '@storybook/theming';
+
+addParameters({
+  options: {
+    theme: themes.dark,
+  },
+});
+```
+
+## CSS escape hatches
+
+The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all of the Docs components are tagged with class names to make this possible. This is advanced usage: use at your own risk.
+
+The classes correspond to markdown elements (e.g. `sbdocs-h1`, `sbdocs-p`, etc.) to UI elements on the page (e.g. `sbdocs-container`, `sbdocs-content`, etc.). To see the currently available classes, simply "inspect element" in your browser.
+
+You can style these classes in `.storybook/preview-head.html`. For example, here's how to make the content wider for UHD displays:
+
+```html
+<style>
+  .sbdocs.sbdocs-content {
+    max-width: 1440px;
+  }
+</style>
+```
+
+> NOTE: All of these elements also have the `sbdocs` class, which is simply an idiomatic way of increasing the CSS specificity so you don't have to use `!important`.
+
+## MDX component overrides
+
+If you're using MDX, there's one more level of themability. MDX allows you to [completely override the components](https://mdxjs.com/advanced/components) that are rendered from markdown using a `components` parameter. This is an advanced usage that we don't officially support in Storybook, but it's a powerful mechanism if you need it.
+
+Here's how you might insert a custom code renderer for `code` blocks on the page, in `.storybook/config.js`:
+
+```js
+import { addParameters } from '@storybook/react';
+import { CodeBlock } from './CodeBlock';
+
+addParameters({
+  docs: {
+    components: {
+      code: CodeBlock,
+    },
+  },
+});
+```
+
+## More resources
+
+Want to learn more? Here are some more articles on Storybook Docs:
+
+- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [FAQ](faq.md) / [Recipes](recipes.md)
+- Vision: [Storybook Docs sneak peak](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a)
+- Announcement: [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf)
+- Example: [Storybook Design System](https://github.com/storybookjs/design-system)
+- [Technical preview guide](https://docs.google.com/document/d/1un6YX7xDKEKl5-MVb-egnOYN8dynb5Hf7mq0hipk8JE/edit?usp=sharing)

addons/docs/src/blocks/DocsContainer.tsx

@@ -68,8 +68,8 @@ export const DocsContainer: React.FunctionComponent<DocsContainerProps> = ({
     <DocsContext.Provider value={context}>
       <ThemeProvider theme={theme}>
         <MDXProvider components={components}>
-          <DocsWrapper>
-            <DocsContent>{children}</DocsContent>
+          <DocsWrapper className="sbdocs sbdocs-wrapper">
+            <DocsContent className="sbdocs sbdocs-content">{children}</DocsContent>
           </DocsWrapper>
         </MDXProvider>
       </ThemeProvider>

examples/official-storybook/preview-head.html

@@ -5,4 +5,8 @@
   #dotenv-file-not-loaded {
     display: %DOTENV_DISPLAY_WARNING%;
   }
+
+  .sbdocs.sbdocs-content {
+    max-width: 600px;
+  }
 </style>

lib/components/src/html.tsx

@@ -6,7 +6,9 @@ export * from './typography/DocumentFormatting';
 export const components = Object.entries(rawComponents).reduce(
   (acc, [k, V]) => ({
     ...acc,
-    [k.toLowerCase()]: (props: object) => <V {...props} className={`sbdocs-${k.toLowerCase()}`} />,
+    [k.toLowerCase()]: (props: object) => (
+      <V {...props} className={`sbdocs sbdocs-${k.toLowerCase()}`} />
+    ),
   }),
   {}
 );