EmcyDocs

Reference

Component Library

Opinionated MDX components for banners, cards, accordions, file trees, tabs, diagrams, and polished code blocks.

7 sections3 locales
Shared primitives

Ship polished docs pages from the same package you publish

EmcyDocs now ships a compact component library so your docs home, product guides, and reference pages can share one visual language instead of drifting repo by repo.

Open theme guide

Why it exists#

Shared chrome

Use the same building blocks in the example app and production docs without splitting another package.

Better defaults

Stop re-inventing card grids, migration banners, and code block wrappers in every repo.

MDX-native

All components register through `getDefaultMdxComponents()` so they work in plain content files.

Hero surface

Use banners to frame a guide, migration, or docs-home announcement

Banners work well at the top of landing pages, major product guides, and release notes when you need more emphasis than a plain paragraph can provide.

Continue

Docs homes

Point new readers at the right namespace, showcase major capabilities, and anchor the docs visual identity.

Guide sections

Break long pages into scannable clusters without falling back to plain unordered lists.

Accordions#

What belongs in an accordion?

Put FAQs, optional setup branches, migration caveats, or product-specific notes here. Keep the title short and action-oriented.

Does it still work with normal markdown?

Yes. You can mix fenced code blocks, headings, lists, tables, and JSX components in the same .mdx file.

Why not depend on another UI package?

EmcyDocs keeps everything in one library on purpose. The components are small, docs-focused, and styled by the same shared stylesheet.

File trees#

site/content/docs
▾reference
•component-library/en.mdxEnglish
•component-library/es.mdxSpanish
•component-library/zh.mdxChinese
•theme-configuration/en.mdxTheme docs
▾layouts
•docs-layout/en.mdxClassic layout
•custom-header-and-sidebar/en.mdxChrome overrides

Tabs and steps#

Import the package once

Add @emcy/docs/styles.css globally and keep your docs content inside the repo.

Use the shared layouts

Start with DocsLayout, then add your own theme, search, locale switching, or chrome overrides as needed.

Reach for components in MDX

Use banners, cards, accordions, files, tabs, and steps where a plain markdown block would feel flat.

Diagrams#

How content flows from MDX files to a rendered docs page
The docs authoring and build lifecycle

Code blocks#

layout.tsx

The goal is straightforward: one package, one visual language, and enough primitives to make docs pages look intentional without creating another package boundary. When you need live theme switching, keep the same DocsLayout and add DocsThemeProvider around it instead of swapping to a different component.