@docubook/markdown 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wildan Nursahidan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# @docubook/markdown
+
+Portable MDX components and framework adapters for [DocuBook](https://docubook.pro/). Provides a collection of ready-to-use React components designed for MDX-based documentation sites, with built-in support for Next.js adapters.
+
+## Installation
+
+```bash
+# npm
+npm install @docubook/markdown
+
+# pnpm
+pnpm add @docubook/markdown
+
+# yarn
+yarn add @docubook/markdown
+
+# bun
+bun add @docubook/markdown
+```
+
+## Usage
+
+### 1. Create a custom components registry
+
+Create `lib/mdx/index.ts` to register your custom MDX components:
+
+```ts
+// lib/mdx/index.ts
+import type { MdxComponentMap } from "@docubook/markdown";
+
+export const customMdxComponents: MdxComponentMap = {
+  // add your custom components here
+};
+```
+
+### 2. Create the MDX components map
+
+Create `lib/mdx-components.ts` to define the full component map. Import built-in components individually and merge them with your custom ones via `createMdxComponents`:
+
+```ts
+// lib/mdx-components.ts
+import {
+    createMdxComponents,
+    type MdxComponentMap,
+    AccordionsMdx,
+    AccordionMdx,
+    CardsMdx,
+    ChangesMdx,
+    CodeBlock,
+    FileMdx,
+    FilesMdx,
+    FolderMdx,
+    KbdMdx,
+    NoteMdx,
+    ReleaseMdx,
+    StepsMdx,
+    StepMdx,
+    TabMdx,
+    TabsMdx,
+    TableBodyMdx,
+    TableCellMdx,
+    TableFooterMdx,
+    TableHeadMdx,
+    TableHeaderMdx,
+    TableMdx,
+    TableRowMdx,
+    MermaidMdx,
+    TooltipMdx,
+    YoutubeMdx,
+} from "@docubook/markdown";
+// Note: the Next.js adapter (`@docubook/markdown/next`) has been removed.
+// Use the base components from `@docubook/markdown` instead.
+import { customMdxComponents } from "@/lib/mdx";
+
+const builtInOverrides: MdxComponentMap = {
+    Tabs: TabsMdx,
+    Tab: TabMdx,
+    table: TableMdx,
+    thead: TableHeaderMdx,
+    tbody: TableBodyMdx,
+    tfoot: TableFooterMdx,
+    tr: TableRowMdx,
+    th: TableHeadMdx,
+    td: TableCellMdx,
+    pre: CodeBlock,
+    Button: ButtonMdx,
+    Note: NoteMdx,
+    Step: StepMdx,
+    Steps: StepsMdx,
+    Accordion: AccordionMdx,
+    Accordions: AccordionsMdx,
+    Card: CardMdx,
+    Cards: CardsMdx,
+    Kbd: KbdMdx,
+    Release: ReleaseMdx,
+    Changes: ChangesMdx,
+    File: FileMdx,
+    Files: FilesMdx,
+    Folder: FolderMdx,
+    Youtube: YoutubeMdx,
+    Tooltip: TooltipMdx,
+    Mermaid: MermaidMdx,
+    img: ImageMdx,
+    a: LinkMdx,
+    Link: LinkMdx,
+};
+
+export const mdxComponents = createMdxComponents({
+    ...builtInOverrides,
+    ...customMdxComponents,
+});
+```
+
+> The Next.js adapter (`@docubook/markdown/next`) has been removed. Use the base components from `@docubook/markdown`.
+
+### 3. Use the components map when rendering MDX
+
+Pass `mdxComponents` to `createMdxContentService` from `@docubook/core`:
+
+```ts
+// lib/markdown.ts
+import { createMdxContentService } from "@docubook/core";
+import { cache } from "react";
+import { mdxComponents as components } from "@/lib/mdx-components";
+
+const docsService = createMdxContentService({
+  parseOptions: { components },
+  cacheFn: cache,
+});
+```
+
+### Available import paths
+
+|              Path              |                          Description                           |
+| ------------------------------ | -------------------------------------------------------------- |
+| `@docubook/markdown`        | All server-safe components + `createMdxComponents` registry    |
+| `@docubook/markdown/client` | Client-only components (accordion, tabs, tooltip, mermaid, etc.)        |
+| `@docubook/markdown/server` | Server-side components                                         |
+| ~~`@docubook/markdown/next`~~ | Removed — Next.js adapter was deleted. Use base components. |
+| `@docubook/markdown/styles.css` | Stylesheet for MDX components (required)                   |
+
+> **Important:** You must import the stylesheet in your app's root layout or global CSS entry point:
+>
+> ```ts
+> import "@docubook/markdown/styles.css";
+> ```
+
+---
+
+## Custom Components
+
+### 1. Create your component
+
+Add a new file under `lib/mdx/`:
+
+```tsx
+// lib/mdx/Callout.tsx
+export default function Callout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="border-l-4 border-blue-500 pl-4 py-2 bg-blue-50">
+      {children}
+    </div>
+  );
+}
+```
+
+### 2. Register your component
+
+Import and add it to `customMdxComponents` in `lib/mdx/index.ts`:
+
+```ts
+// lib/mdx/index.ts
+import type { MdxComponentMap } from "@docubook/markdown";
+import Callout from "@/lib/mdx/Callout";
+
+export const customMdxComponents: MdxComponentMap = {
+  Callout,
+};
+```
+
+`customMdxComponents` is already spread into `createMdxComponents` in `lib/mdx-components.ts`, so no further changes are needed. You can now use `<Callout>` in any `.mdx` file:
+
+```mdx
+<Callout>
+  This is a custom callout component.
+</Callout>
+```
+
+---
+
+## Customization
+
+All components expose stable CSS class names you can target for style overrides. Import `@docubook/markdown/styles.css` for base styles, then override as needed.
+
+### CSS Classes
+
+|              Class               |  Component   |                    Description                    |
+| -------------------------------- | ------------ | ------------------------------------------------- |
+| `.mdx-expandable-code`           | `CodeBlock`  | The `<pre>` element inside expandable code blocks |
+| `.mdx-expandable-code-container` | `CodeBlock`  | Scroll container wrapping the `<pre>`             |
+| `.code-block-container`          | `CodeBlock`  | Outer wrapper of the entire code block            |
+| `.code-block-header`             | `CodeBlock`  | Header bar (filename, language label)             |
+| `.code-block-actions`            | `CodeBlock`  | Action buttons area (copy button)                 |
+| `.code-block-body`               | `CodeBlock`  | Body area containing the code                     |
+| `.code-block-expandable-footer`  | `CodeBlock`  | Footer with expand/collapse toggle                |
+| `.code-block-expandable-toggle`  | `CodeBlock`  | The expand/collapse button                        |
+| `.docubook-card-group`           | `Cards`      | Grid container for card layouts                   |
+| `[data-card-hover]`              | `Card`       | Card with link — target for hover styles          |
+| `[data-card-icon]`               | `Card`       | Icon element inside a card                        |
+| `.mdx-accordion`                 | `Accordion`  | Single accordion wrapper                          |
+| `.mdx-accordion-group`           | `Accordions` | Group wrapper for multiple accordions             |
+| `.mdx-accordion-group-item`      | `Accordion`  | Accordion when inside a group                     |
+| `.mdx-accordion-header`          | `Accordion`  | Clickable header/trigger                          |
+| `.mdx-accordion-chevron`         | `Accordion`  | Chevron icon in header                            |
+| `.mdx-accordion-content`         | `Accordion`  | Collapsible content area                          |
+
+### CSS Custom Properties
+
+|             Variable             | Component |                       Description                        |
+| -------------------------------- | --------- | -------------------------------------------------------- |
+| `--docubook-card-group-template` | `Cards`   | Grid column template (set automatically via `cols` prop) |
+
+---
+
+## API Migration Policy
+
+The current rename rollout uses a migration phase, not an immediate hard-breaking change:
+
+- New tags are the primary API (`Accordions`, `Cards`, `Steps`, `Step`).
+- Legacy tags are still supported as deprecated aliases for backward compatibility `only v2`(`AccordionGroup`, `CardGroup`, `Stepper`, `StepperItem`).
+- A true breaking change happens when deprecated aliases are removed in a future major release. `v3 remove legacy API`
+
+---
+
+## Available Components
+
+Components included out of the box:
+
+- `Accordion` / `Accordions`
+- `Button`
+- `Card` / `Cards`
+- Code Block (`pre`)
+- `Files` / `Folder` / `File`
+- `Image` / `img`
+- `Kbd`
+- `Link` / `a`
+- `Note`
+- `Release` / `Changes`
+- `Steps` / `Step`
+- `Tabs` / `Tab`
+- `Tooltip`
+- `Mermaid` — renders Mermaid.js diagrams (flowchart, sequence, class, state, gantt, pie, ER) from ` ```mermaid ` fenced code blocks, with GFM-style pan/zoom/fullscreen controls (button and keyboard driven)
+- `Youtube`
+- Table (`table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`)
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/DocuBook/docubook/blob/main/packages/markdown/LICENSE) for details.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { ComponentType } from 'react';
+
+type MdxComponentMap = Record<string, ComponentType<any>>;
+declare function createMdxComponents(customComponents?: MdxComponentMap): MdxComponentMap;
+
+export { type MdxComponentMap, createMdxComponents };