What is sidecar.mdx?

Sidecar.mdx is a special type of file used in documentation and component libraries. It combines Markdown (a simple way to write formatted text) with JSX (a syntax that lets you embed interactive UI components). The “sidecar” part means the file lives alongside a component’s code, providing extra information like usage examples, props tables, or design notes without changing the component itself.

Let's break it down

  • Markdown: Plain‑text language for headings, lists, links, and code blocks. Easy to read and write.
  • MDX: Extends Markdown so you can insert JSX tags directly inside the text.
  • Sidecar: The file sits next to a component (e.g., Button.jsx) and is named the same but with the .mdx extension (Button.sidecar.mdx). It “rides along” with the component, hence the name.

Why does it matter?

Sidecar.mdx keeps documentation close to the code it describes, which means:

  • Developers see docs and code together, reducing the chance of outdated information.
  • Teams can write interactive examples that run right in the docs, making learning faster.
  • It supports a single source of truth: one place to update both the component and its guide.

Where is it used?

  • Design systems (e.g., Storybook, Chakra UI) to show live component demos.
  • Open‑source libraries that want to ship readable docs with the package.
  • Internal company wikis where engineers need quick, interactive references.
  • Static site generators like Docusaurus that render MDX files as web pages.

Good things about it

  • Live examples: Readers can interact with the component directly in the doc.
  • Co‑location: Docs stay next to the component, making maintenance easier.
  • Flexibility: You can mix plain text, code snippets, and real UI components.
  • Tooling support: Many modern frameworks (Next.js, Gatsby) understand MDX out of the box.
  • Version control: Changes to code and docs are tracked together in Git.

Not-so-good things

  • Build complexity: Projects need MDX loaders or plugins, adding extra setup steps.
  • Learning curve: Beginners must grasp both Markdown and JSX syntax.
  • Performance: Rendering many interactive examples can slow down documentation sites if not optimized.
  • File clutter: Adding a sidecar file for every component can increase the number of files in a repo.
  • Tool compatibility: Some older static site generators or CI pipelines may not support MDX without upgrades.