[RFC] Allow overriding individual doc blocks in autodocs

[JReinhold]

Status: in-review; championed by @JReinhold

Note Even though I am a core team member of Storybook, that doesn't mean that this proposal is on the roadmap, or will ever be implemented. These are my individual thoughts and haven't been prioritised at all.

Summary

This RFC is a proposal to make it possible to override individual blocks in the autodocs page, without having to override and re-implement the whole page. Blocks will be overridable via parameters, similar to how the docs page and container is overridable today.

Problem Statement

Sometimes users want to override just a portion of the autodocs page, but overall keep the same content. Examples include:

• Change the Canvas, to support multiple different source views
• Change the Description to contain default disclaimers next to the actual story descriptions
• Change the Title to be based on something else than the component title

To eg. change the Description today, the user has to go through a somewhat cumbersome process:

1. Add your own custom docs page to parameters.docs.page - most likely in preview.js
2. In that custom docs page, copy the default DocsPage content in (from the Storybook source), except for the Stories component
3. Same for the Stories component, except with a custom DocsStory component
4. Same for the DocsStory component, except for a custom Description component
5. Write the custom Description behavior

Non-goals

• Supporting custom components between parents and children. Eg. if you're both overriding DocsStory it's direct child Description, we shouldn't try to get the custom Description to work. If you're overriding DocsStory, you are responsible for all the direct children to be your custom implementation too. (Although non-direct descendants like Stories -> Description should work)
• Supporting overriding any component in the manager UI, this is just the doc blocks.

Implementation

Similar to how you can override the default docs page and container at parameters.docs.page and parameters.docs.container, I propose a solution that allows you to override the individual blocks in an autodocs via parameters.

So if you wanted to have a custom description, you would only override that, and not the full tree of the docs page:

// preview.ts
import { CustomDescription } from './CustomDescription.tsx';
// OR
import CustomDescription from './CustomDescription.mdx';

export default {
  parameters: {
    docs: {
      blocks: {
        description: CustomDescription
      }
    }
  }
}

The following blocks would be valid to override:

• Page (already possible)
• Title
• Subtitle
• Description
• Primary
• Controls
• Stories
• DocsStory
• Anchor (maybe?)
• Canvas
• Source (if possible?)

Proposed API

I can come up with 2 different APIs for this:

1. A map of blocks

export default {
  parameters: {
    docs: {
      blocks: {
        description: CustomDescription,
        stories: ...,
        primary: ...,
      }
    }
  }
}

Possible property names (we should choose one):

• blocks
• components - We already use this today to override MDX components (unsupported)
• templates - if you're writing them with MDX, this might match the mental model
• overrides - similar to MDX2 API

2. A property under each (existing) block property

export default {
  parameters: {
    docs: {
      description: {
        block: CustomDescription,
      },
      priamry: {
        block: ...,
      },
      stories: {
        block: ...,
      },
    }
  }
}

I feel this API is more closely aligned with our existing API, and I'm leaning towards this. A minor thing to consider here is that parameters.docs.description.component is already a property, so we wouldn't be able to use component as a prop name there.

Docs Page and Container overrides

Irregardless of which API we choose, we need to decide what to do abut the existing functionality for overriding the Docs page and container at parameters.docs.page|container, as it wouldn't be consistent with overriding the other blocks. There are multiple possibilities here as well:

1. Keep parameters.docs.page as-is.
2. Follow the other blocks and move it to either parameters.docs.blocks.page or parameters.docs.page.block
3. Support both.

The current API is problematic if we want to support adding options to the docs page/container at some point in the future. Eg. you can't at support for parameters.docs.page.rightAligned because parameters.docs.page is already supposed to be a function.

Prior Art

• As mentioned it's already possible to override the docs page and container, implemented here: https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/blocks/Docs.tsx
  See https://storybook.js.org/docs/react/writing-docs/autodocs

• This is similar to what fwoosh supports https://fwoo.sh/docs/Theming-Introduction#component-overrides

Deliverables

Not planned yet.

Risks

• This will increase the surface area of docs and documentation about docs unproportionally to the value it would give users. This might be an edge case that not many users care about in reality. A counter argument here, is that looking at the existing implementation for custom docs page and container, it's about 3 lines of code for each.
• Similar to above, this would make it more difficult to make changes to the internal structure of a DocsPage (and below). It would mean that any change to props passed to the blocks (internally) would be a breaking change, because that is now a public facing API. This is okay if we think the blocks are fairly stable.

Unresolved Questions

• What should the API structure for this be exactly?
• What do we do about the existing API for overriding docs pages and containers?
• Should we make it possible to override the Anchor, or do we consider that an internal API?
• Is it possible to override the Source block directly (which is always contained within the Canvas block), or is that too intertwined with the Canvas block?
• Are there any pitfalls for supporting this with MDX in non-React projects?

Alternatives considered / Abandoned Ideas

No response

[kylegach]

Nice idea! A few thoughts:

Non-goals

• Supporting custom components between parents and children. Eg. if you're both overriding DocsStory it's direct child Description, we shouldn't try to get the custom Description to work. If you're overriding DocsStory, you are responsible for all the direct children to be your custom implementation too. (Although non-direct descendants like Stories -> Description should work)

I had to read this three times, but I think I understand now. 😅 I agree with this: "If you're overriding DocsStory, you are responsible for all the direct children to be your custom implementation too." To make this easier, could the implementation of this feature expose the custom implementation (which falls back to the default) to be able to use? e.g.

function CustomDocsStory({ blocks }) {
  const { Description } = blocks
  return (
    // Bunch of other stuff
    <Description />
  )
}

Or make it a hook:

import { useBlocks } from '@storybook/blocks'

function CustomDocsStory() {
  const { Description } = useBlocks
  return (
    // Bunch of other stuff
    <Description />
  )
}

A property under each (existing) block property

I also prefer this API (option 2).

The current API is problematic if we want to support adding options to the docs page/container at some point in the future. Eg. you can't at support for parameters.docs.page.rightAligned because parameters.docs.page is already supposed to be a function.

Unless we feel strongly that we will be adding such options in the future, I prefer keeping parameters.docs.page.

Btw, related to my suggestion above, could the implementation change to:

parameters: {
  docs: {
    page: ({ blocks }) => {
      const { Title, Subtitle, Description, Primary, Controls, Stories } = blocks
      return (
        <Title />
        // ...
      )
    }
  }
}

Where blocks.* would either be parameters.docs.*.block or the default component. This lets consumers separate the customization of, say, Title, from the customization of the template. Perhaps overkill.

[JReinhold]

To make this easier, could the implementation of this feature expose the custom implementation (which falls back to the default) to be able to use? e.g.

I have to think about this some more. Your first suggestion of passing them in as props wouldn't be very ergonomic to implement, as it would require the parent components to define to know which components their children needed. But I could maybe see the hook work, because essentially useBlocks would do the same as importing the blocks from @storybook/blocks, except it would use the custom implementations when defined. This feels like a minimal thing to document and support.

Unless we feel strongly that we will be adding such options in the future, I prefer keeping parameters.docs.page.

Noted, I don't have strong feelings about it.

Btw, related to my suggestion above, could the implementation change to:

parameters: {
  docs: {
    page: ({ blocks }) => {
      const { Title, Subtitle, Description, Primary, Controls, Stories } = blocks
      return (
        <Title />
        // ...
      )
    }
  }
}

Where blocks.* would either be parameters.docs.*.block or the default component. This lets consumers separate the customization of, say, Title, from the customization of the template. Perhaps overkill.

This would be solved with the useBlock hook too, no?

[kylegach]

This would be solved with the useBlock hook too, no?

Yeah, totally.

[tmeasday]

@JReinhold did you think about using parameters.docs.components for this? These can be used to override the default MDX components, would it make sense to also read the blocks from this list?

[JReinhold]

I briefly considered it, but I wasn't sure how it would interact with the MDX provider, if that would cause some conflicts or not. But if not, I like the idea of just "expanding" the existing API - it's even listed as possible options in the RFC.

I'm unsure if it would be confusing to mix MDX overrides with block overrides. Currently we don't officially support MDX overrides (per the docs), so our communication would be "we support overrides of default blocks at parameters.docs.components.Stories, but not any other components like parameters.docs.components.h1"). Maybe having a clearer separation between the two is valuable just from a documentation perspective.

Thoughts @kylegach ?

[kylegach]

Oh, hmm... This bit of the docs would imply that we already have the API:

We would still need to update the implementation of each block to use the provided component and fallback to the default.

---

Currently we don't officially support MDX overrides (per the docs), so our communication would be "we support overrides of default blocks at parameters.docs.components.Stories, but not any other components like parameters.docs.components.h1")

If it's not too much effort to fully support the MDX provider API (thus eliminating this limitation), that seems like a sound approach to me.

[tmeasday]

I'm not 100% sure what the docs even mean there when they say "Currently we don't officially support MDX overrides..." then show you how to do it :)

[JReinhold]

Just to be clear, the MDX provider overrides only trigger when you use the components in MDX. If you override Canvas with the provider, and have a Wrapper in MDX which is a React component that uses Canvas, then that Canvas will not be overwritten, because it was not in the MDX, but in the React component.

The limitation of mixing MDX provider overrides and block overrides with the same API, would be that if you override the Description block, it would also override any Description block usage directly in MDX, because the MDX Provider would pick up the overrides as well. That is at least my assumption, but I'd have to try some stuff out to be sure.

I'm not 100% sure what the docs even mean there when they say "Currently we don't officially support MDX overrides..." then show you how to do it :)

I agree, I would also think that documenting something is the definition of supporting it.

[shilman]

Nice feature and excellent writeup.

Seems like you're leaning towards docs.*.block and I prefer docs.blocks.*. The reason is that in the future I'd like to create addons for all the doc blocks and then hoist the parameters. So docs.controls.* would be controls.*, but you might still want to override the doc block per this proposal.

I'm also concerned with growing our surface area and constraining ourselves in unknown ways. But I can live with it.

[donaldpipowitch]

Hi, I'd like to follow up on this RFC based on this Twitter exchange. I documented my use case here (- hide all <Canvas/>' except the first one by default to get a better rendering performance). Right now I solve this by duplicating a lot of built in components, but this is error prone and hard to synchronize during Storybook updates.

I proposed a solution that matches this RFC and basically used the same API as "Proposed API 1.". (This seemed more natural to me as it matches how you override MDX components.) But I'd also be happy to support in contributing to "Proposed API 2.".

For the time being I'd keep parameters.docs.page|container. Maybe this can be deprecated in the future.