contribution/documentation

15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Edit documentation using GitHub web interface

To fix a typo or clarify a section of the Storybook docs, scroll to the bottom of the documentation page in question and click the ✍️ Edit on GitHub button. This opens the Markdown file on GitHub. Use GitHub's web editor by clicking the pencil icon in the right-hand corner to make edits to the document.

Submit documentation changes as a pull request

After editing a documentation file on GitHub, scroll to the bottom of the page and describe what you changed and why. Select the option 'Create a new branch for this commit and start a pull request' and click the 'Propose changes' button. In the Storybook repository, create a pull request that describes changes and includes additional context to help maintainers review. Once submitted, a maintainer will guide you through the triage and merge process.

Documentation improvement process overview

Documentation improvements, typos, and clarifications follow a standard contribution process through pull requests. This is one of several contribution paths in Storybook, alongside the RFC process for feature requests, code contributions for features and bug fixes, framework contributions, and example snippets.

Code snippets directory structure

Code snippets referenced throughout the Storybook documentation are located in the docs/_snippets directory inside individual Markdown files. Each file contains snippets for supported frameworks, features, and languages (JavaScript, MDX, TypeScript).

Supported frameworks for code snippets

Storybook maintains code snippets for React, Vue 3, Angular, Web Components, Svelte, Solid, Preact, and Qwik. Ember, HTML, and other frameworks do not currently have snippets available.

filename attribute in code snippets

Most code examples should include a filename attribute wrapped with quotation marks to indicate the file name. This helps readers understand which file the example relates to and where to paste it into their project. The filename attribute is not required if the example relates to a terminal command.

language attribute for code snippet variants

Use the language attribute to define the language to which the code snippet applies (js, ts, or mdx). The documentation uses this attribute to determine which variant to display.

renderer attribute for framework-specific snippets

Use the renderer attribute to indicate which framework the code snippet belongs to. Supported values are: react, vue, angular, web-components, ember, html, svelte, preact, qwik, and solid. Use renderer="common" for code snippets that apply to multiple frameworks or are framework-agnostic.

packageManager attribute for terminal commands

Use the packageManager attribute to configure the package manager used in terminal command examples. Supported values are: npm, yarn, or pnpm.

tabTitle attribute for multiple snippets in one file

Use the tabTitle attribute to indicate the tab title in which the code snippet will be displayed. This attribute should only be used when multiple examples are in a single code snippet file.

Code snippet contribution workflow

To contribute code snippets, create a new branch with 'git checkout -b code-snippets-for-framework', locate the relevant file in docs/_snippets directory using the CodeSnippets path component in documentation files, adjust the snippet content to match your framework, and repeat for all relevant documentation pages.

Preview code snippet changes locally

To preview snippet changes before submitting: fork the Storybook website repository, clone it locally, run 'npm install' in the web directory, run 'npm run build:frontpage' to generate a website build, run 'npm run sync-docs' to connect documentation from the Storybook monorepo (providing the path to your local fork and documentation version when prompted), and finally run 'npm run dev' in a new terminal. Open http://localhost:3000 to preview changes.

packageManager attribute with multiple examples pitfall

If you're documenting an example that includes the packageManager attribute combined with another example, the documentation might not display the code snippets correctly. To avoid this, divide the examples into separate files and reference them in the documentation.

Syntax highlighting limitations in Storybook MDX

Storybook MDX provides out-of-the-box syntax highlighting for Javascript, Markdown, CSS, HTML, Typescript, and GraphQL. There is a known limitation when registering custom languages for syntax highlighting, and a fix is being developed.

MDX style formatting with line breaks breaks styling

In Storybook MDX, wrapping style blocks with line breaks between opening tags and template literal breaks styling. Correct: <style>{`...`}</style>. Incorrect: <style>{` ...`}</style> (with line breaks inside the template literal after opening brace).

Give your agent this brain