Given a global custom AutoDocs template, how can I dynamically add imports or content at the story level?

[katcaola]

Dependecies / Problem Statement

I have a component library that uses Storybook 7.5.1.

Our component folders are set up like this:

src/components/someComponent
├── someComponent.component.ts
├── someComponent.stories.ts
├── someComponent.styles.scss
├── someComponent.test.ts
└── readme.md

Given this structure, it would be nice to be able to be able to import the readme.md for every component into each *.stories.ts.

The reason for this is that the readme.md gets rendered when looking at the code base (locally or on our server) and has component requirements and other information that is not in the generated autodocs stories. I would like to also make sure this information is available in our stories so that it appears in our hosted storybook instance, which is more accessible to non-technical folks (such as UI/UX, managers, and others who may not have access to our code base).

The AutoDocs are also nice because the developers do not have to write the documentation, they just have to fill in parameters, and storybook renders the rest (they have historically been bad at upkeeping documentation 😅). We also have a unit test rule where if you have requirements in the readme.md and do not create corresponding unit tests, the build will fail, so this encourages developers to have requirements in the readme.md and create unit tests.

Thus, it would be nice to use the files we already have and keep the process as auto-generated as possible.

Research

According to the storybook docs, I have found that storybook allows for a custom autodocs page template via a *.mdx file.

Inside my .storybook/preview.ts I have my custom autodoc page:

import CustomDocsPage from './CustomDocsPage.mdx';
import type { Preview } from "@storybook/web-components";

const preview: Preview = {
  parameters: {
    ...
    docs: {
      ...
      page: CustomDocsPage,
    }
  }
};

export default preview;

Inside my CustomDocsPage.mdx I want to be able to do something like this:

[...]
<Markdown>{readme}</Markdown>
[...]

I have found that I can do something very similar via a non-template *.mdx such as SomeComponent.mdx with the following content:

import { Meta, Markdown} from '@storybook/blocks';
import SomeComponentStories from "./ someComponent.stories.ts";
import readme from './readme.md?raw';

<Meta of={ SomeComponentStories} />

<Markdown>{readme}</Markdown>

However, this is not ideal because:

• This creates a new additional documentation page under each component. I would like all information to be in one document under each component.
• I need a whole other file (SomeComponent.mdx) just to display a readme.md that already exists, and I would need one for every component. I would rather have a global CustomDocsPage.mdx that I could change per story.

What I've tried and don't understand

I first tried to create a global parameter in my preview.ts

const preview: Preview = {
  parameters: {
    ...
    docs: {
      readmePath: "./readme.md?raw",
      page: DocumentationTemplate,

But that did not work.

I also tried to overwrite it at the story level in my someComponent.stories.ts

import type { StoryObj } from "@storybook/web-components";
import readme from './readme.md?raw';

export default {
    parameters: {
        docs: {
            readmePath: readme,
        },
    },

But this didn't work either.

I then wondered if it was a shortcoming of MDX, but after looking at the MDX github discussions, it appears that Storybook and webpack handle imports.

Thus my questions:

1. Is what I'm trying to do even possible?
2. If it is possible, how do I dynamically import the readme.md path into my AutoDoc template's <Markdown></Markdown> component?
3. Or if I can't do dynamic imports, how do I dynamically import the readme.md content into my AutoDoc template's <Markdown></Markdown> component?

For those also looking to score some internet points, it looks like there is a similar question on Stack Overflow here.

[Dtsiantaris]

Hey @katcaola!

I've been trying to do something similar too. Did you find a solution?

[smlimasu]

You can dynamically insert content into the docs page template setting up the docs page as a react component. I've shown an example here #29156

But instead of guide you pass your imported md.raw file as a parameter to a markdown block in the template.

I am somewhat confident that you could also read the meta/story importPath dynamically in the template and do a dynamic import like import.module(pathtomdInTheStoriesFolder) setup which would eliminate the need to pass the md file at the story level every time.

Here is an example to access some meta or story data #29445 if you need to I could try it out for MD files and import paths and provide a detailed working snippet, too.

[Dtsiantaris]

This was one of the best github answers I have ever received!

Basically the DocsContext is exactly what I needed..and to be honest I think it's a same it is not introduced in the official docs(unless it is and I've missed it?)

Appreciate your help my friend, thank you 👊!

[smlimasu]

It is not well documented, indeed, after months of trying stuff out with headache I finally got more understanding of the mechanisms while looking at the source code of the storybook blocks components. Thank you!

It would be very helpful if you could provide your snippet / final solution with some docs context for other people searching for a md solution in the future, here too!

Cause I think that's also a path to a solution for people who want to import the TS or HTML files of their components into the docs page

[Dtsiantaris]

Well my issue was generally Vue specific.

I wanted to be able to use SFCs for most of my stories.

I created a vite plugin that extracts the source code using a virtual module and then using it like that for example:

import BasicUsageStorybook from "src/stories/components/ComponentName/templates/BasicUsage.storybook.vue";
import BasicUsageSourceCode from "src/stories/components/ComponentName/templates/BasicUsage.storybook.vue?sourceCode";

export const BasicUsage: Story = {
  globals: {
    source: BasicUsageSourceCode,
  },
  render: () => h(BasicUsageStorybook),
};

The I just used your solution and a CustomStoryCanvas component to display the source code in 'chunks':

//DocsPage.tsx
import React, { useContext } from "react";

import {
  Subheading,
  Meta,
  DocsContext,
  Controls,
  Title,
  Markdown,
  Description,
  Heading,
} from "@storybook/blocks";
import { CustomStoryCanvas } from "./CustomCanvas";

export const CustomDocsPageTemplate: React.FC = () => {
  const {
    componentStories,
    projectAnnotations,
    getStoryContext,
    primaryStory,
  } = useContext(DocsContext);

  // Get all csf file stories
  let stories = componentStories();

  // base filter all csf file stories
  const { stories: { filter } = { filter: undefined } } =
    projectAnnotations.parameters?.["docs"] || {};
  if (filter) {
    stories = stories.filter((story) => filter(story, getStoryContext(story)));
  }

  // Filter to only include stories with 'autodocs' tags
  stories = stories.filter(
    (story) => story.tags?.includes("autodocs") && !story.usesMount
  );

  const getSourceCodeObj = (story) => {
    return (
      story.moduleExport.globals?.source ??
      story.moduleExport.parameters.docs.source.originalSource
    );
  };

  return (
    <>
      <Meta />
      <Title />
      <Description />
      <CustomStoryCanvas
        story={primaryStory}
        sourceCodeObj={getSourceCodeObj(primaryStory)}
      />
      <Controls />
      <Heading>Stories</Heading>
      <div>
        {stories.map(
          (story) =>
            story && (
              <>
                <Subheading>{story?.name || ""}</Subheading>
                <Markdown>
                  {story.parameters["docs"]?.description?.story || ""}
                </Markdown>
                <CustomStoryCanvas
                  story={story}
                  sourceCodeObj={getSourceCodeObj(story)}
                />
              </>
            )
        )}
      </div>
    </>
  );
};

And the canvas:

import React, { useState } from "react";

import {
  TabBar,
  TabButton,
  Button,
  SupportedLanguage,
} from "@storybook/components";
import { Source, Canvas, Unstyled } from "@storybook/blocks";

import "./templateCss.css";

export const CustomStoryCanvas: React.FC = ({ story, sourceCodeObj }) => {
  const [showCode, setShowCode] = useState(false);

  type SourceTab = "template" | "script" | "all";
  const [activeSourceTab, setActiveSourceTab] = useState<SourceTab>("template");

  const toggleShowCode = () => {
    setShowCode(!showCode);
  };

  const getSourceCode = ():
    | { code: string; language: SupportedLanguage }
    | undefined => {
    if (typeof sourceCodeObj === "string") {
      return { code: sourceCodeObj, language: "tsx" };
    }

    switch (activeSourceTab) {
      case "all":
        return { code: sourceCodeObj.all, language: "html" };
      case "template":
        return { code: sourceCodeObj.template, language: "html" };
      case "script":
        return { code: sourceCodeObj.script, language: "typescript" };
      default:
        break;
    }
  };

  const TabsWithSource: React.FC = () => {
    return (
      <>
        <TabBar style={{ position: "absolute", top: 0, right: 0, zIndex: 20 }}>
          <TabButton
            value="template"
            active={activeSourceTab === "template"}
            onClick={() => setActiveSourceTab("template")}
          >
            template
          </TabButton>
          <TabButton
            value="script"
            active={activeSourceTab === "script"}
            onClick={() => setActiveSourceTab("script")}
          >
            script
          </TabButton>
          <TabButton
            value="all"
            active={activeSourceTab === "all"}
            onClick={() => setActiveSourceTab("all")}
          >
            all
          </TabButton>
        </TabBar>
      </>
    );
  };

  return (
    <>
      <div>
        <div style={{ position: "relative" }}>
          <Canvas
            of={story.moduleExport}
            sourceState="none"
            withToolbar
            className="m-0"
          />
          <Button
            onClick={toggleShowCode}
            style={{
              position: "absolute",
              right: 0,
              bottom: 0,
            }}
          >
            {showCode ? "Hide Code" : "Show Code"}
          </Button>
        </div>
      </div>

      {showCode && (
        <div style={{ position: "relative" }}>
          {typeof sourceCodeObj != "string" && <TabsWithSource />}
          <Unstyled
            style={{
              margin: 0,
            }}
          >
            <Source
              code={getSourceCode()?.code}
              language={getSourceCode()?.language}
              dark
            />
          </Unstyled>
        </div>
      )}
    </>
  );
};