diff --git a/.github/assets/screenshot.png b/.github/assets/screenshot.png new file mode 100644 index 0000000..3a13d87 Binary files /dev/null and b/.github/assets/screenshot.png differ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 8015a87..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,130 +0,0 @@ -# Architecture - -This document describes the internal design and development workflow of Markstage. - -## Repository Layout - -``` -markstage/ -├── packages/ -│ ├── core/ # @markstage/core — programmatic API -│ │ ├── src/ # Node-side code (Vite config, plugins, config loading) -│ │ │ ├── index.ts # Public API: startDev, runBuild, defineConfig, etc. -│ │ │ ├── config.ts # PreviewerConfig type + defineConfig helper -│ │ │ ├── load-config.ts # Loads previewer.config.* via c12 -│ │ │ ├── vite-config.ts # Assembles the full Vite InlineConfig -│ │ │ └── plugins/ # Vite plugins -│ │ │ ├── previewer-code.ts # Transforms ```tsx preview blocks -│ │ │ ├── previewer-entries.ts # Virtual module: preview MDX entries -│ │ │ ├── previewer-config.ts # Virtual module: config -│ │ │ ├── previewer-css.ts # Virtual module: host CSS -│ │ │ ├── previewer-html-title.ts # HTML title injection -│ │ │ └── previewer-llms-txt.ts # llms.txt endpoint -│ │ └── app/ # Browser-side React app (served by Vite) -│ │ ├── index.html -│ │ └── src/ -│ │ ├── main.tsx # React entry -│ │ ├── app.tsx # Shell: sidebar + content area -│ │ ├── overview.tsx # Overview grid page -│ │ ├── preview-block.tsx # Live preview + collapsible code -│ │ ├── code-block.tsx # Shiki syntax highlighting -│ │ ├── mdx-components.tsx # MDX component overrides -│ │ ├── theme.tsx # Dark/light theme provider -│ │ └── virtual-modules.d.ts # Type declarations for virtual modules -│ └── cli/ # @izumisy/markstage — CLI entry point -│ └── src/ -│ ├── cli.ts # Entry point — `dev` and `build` commands (citty) -│ └── index.ts # Re-exports defineConfig from @markstage/core -├── turbo.json # Turborepo task definitions -├── pnpm-workspace.yaml # pnpm workspace config -└── .github/workflows/ci.yml # CI: format check + lint -``` - -## Key Design Decisions - -### Vite as the Runtime - -Markstage does **not** ship a bundled app. Instead it constructs a Vite -`InlineConfig` at runtime and calls `createServer()` (dev) or `build()`. -The `app/` directory is used as Vite's `root`, so `app/index.html` is served -directly without middleware. - -### Virtual Modules - -Three Vite virtual modules inject dynamic data into the browser app: - -| Module | Purpose | -|--------|---------| -| `virtual:previewer-entries` | Imports every discovered `*.preview.mdx` and exports an `entries` array with name, Component, frontmatter, and filePath. | -| `virtual:previewer-config` | Exports `title` and `repo` so the app can render headers and source links. | -| `virtual:previewer-css` | Emits an `@import` for the host project's CSS file (or nothing). | - -### Plugin Pipeline - -Files go through several transformations before reaching the browser: - -1. **`vite-plugin-preview-code`** (enforce: `pre`) — rewrites `` ```tsx preview `` - fenced blocks into `` JSX so the MDX - compiler sees standard markup. -2. **`@mdx-js/rollup`** (enforce: `pre`) — compiles MDX to JSX with remark - plugins: - - `remark-gfm` — GitHub-flavoured markdown. - - `remark-frontmatter` + `remark-mdx-frontmatter` — parse and export YAML - frontmatter. -3. **`@vitejs/plugin-react`** — handles JSX/TSX compilation. - -### Framework Isolation - -Markstage bundles its own `@mdx-js/react` and resolves it via a Vite alias so -the host project does not need to install it. - -## Build - -Both `@markstage/core` and `@izumisy/markstage` (CLI) are compiled with -**tsdown** (a fast TypeScript bundler built on esbuild / Rollup): - -```bash -pnpm build # turbo run build -``` - -**@markstage/core** entry points (`packages/core/tsdown.config.ts`): - -- `src/index.ts` → `dist/index.mjs` + `dist/index.d.mts` (programmatic API) - -**@izumisy/markstage** entry points (`packages/cli/tsdown.config.ts`): - -- `src/cli.ts` → `dist/cli.mjs` (the bin executable) -- `src/index.ts` → `dist/index.mjs` + `dist/index.d.mts` (re-exports from core) - -The `app/` directory (in `packages/core/`) is **not** compiled — it is shipped -as-is and processed by Vite at runtime in the host project. - -## Development - -```bash -pnpm install # install all workspace dependencies -pnpm dev # tsdown --watch (rebuild on change) -pnpm type-check # tsc --incremental -pnpm lint # oxlint -pnpm fmt # oxfmt --write -pnpm fmt:check # oxfmt --check (CI) -``` - -All commands are orchestrated by Turborepo. Run them from the repo root and -Turbo will execute the correct scripts in each workspace package. - -## CI - -GitHub Actions (`.github/workflows/ci.yml`) runs on pushes to `main` and on -pull requests: - -1. `pnpm fmt:check` — verify formatting with oxfmt. -2. `pnpm lint` — run oxlint. - -## Adding a New Package - -1. Create a directory under `packages/`. -2. Add a `package.json` with the desired name and scripts. -3. If the new package has `build`, `lint`, `fmt`, `fmt:check`, or `type-check` - scripts, Turbo will pick them up automatically via the task definitions in - `turbo.json`. diff --git a/README.md b/README.md index 0652434..6008650 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,36 @@ -# Markstage +# md-react-preview -A lightweight toolkit for live-previewing React components directly from Markdown. Write `` ```tsx preview `` fenced blocks and get instant rendered output — powered by Vite. +[![CI](https://github.com/IzumiSy/markstage/actions/workflows/ci.yml/badge.svg)](https://github.com/IzumiSy/markstage/actions/workflows/ci.yml) + +A lightweight toolkit for live-previewing React components directly from Markdown. Write ` ```tsx preview ` fenced blocks and get instant rendered output — powered by Vite. + +![screenshot](.github/assets/screenshot.png) ## Packages -| Package | Description | -|---------|-------------| -| [`@izumisy/markstage`](packages/markstage/) | CLI & programmatic API — run a standalone preview server with `markstage dev` / `markstage build` | -| [`@izumisy/react-preview`](packages/react-preview/) | Vite plugin & utilities — preview block parsing, iframe rendering, standalone preview page generation | -| [`@izumisy/vitepress-plugin-react-preview`](packages/vitepress-plugin-react-preview/) | VitePress plugin — live React component previews inside a VitePress site | +| Package | Description | +| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| [`@izumisy/md-react-preview`](packages/md-react-preview/) | CLI & programmatic API — run a standalone preview server with `mrp dev` / `mrp build` | +| [`@izumisy/vite-plugin-react-preview`](packages/vite-plugin-react-preview/) | Vite plugin & utilities — preview block parsing, iframe rendering, standalone preview page generation | +| [`@izumisy/vitepress-plugin-react-preview`](packages/vitepress-plugin-react-preview/) | VitePress plugin — live React component previews inside a VitePress site | ## Examples -| Example | Description | -|---------|-------------| -| [`example-cli`](examples/cli/) | Standalone preview server using the `@izumisy/markstage` CLI | +| Example | Description | +| ------------------------------------------ | -------------------------------------------------------------------- | +| [`example-cli`](examples/cli/) | Standalone preview server using the `@izumisy/md-react-preview` CLI | | [`example-vitepress`](examples/vitepress/) | VitePress integration with `@izumisy/vitepress-plugin-react-preview` | ## Quick Start ```bash -pnpm add -D @izumisy/markstage +pnpm add -D @izumisy/md-react-preview -npx markstage dev # dev server (port 3040) -npx markstage build # static build +npx mrp dev # dev server (port 3040) +npx mrp build # static build ``` -See the [`@izumisy/markstage` README](packages/markstage/) for configuration and usage details. +See the [`@izumisy/md-react-preview` README](packages/md-react-preview/) for configuration and usage details. ## License diff --git a/examples/cli/README.md b/examples/cli/README.md index 7eb3e12..6dfaf7b 100644 --- a/examples/cli/README.md +++ b/examples/cli/README.md @@ -1,6 +1,6 @@ # example-cli -Example project using the `@izumisy/markstage` CLI. +Example project using the `@izumisy/md-react-preview` CLI. ## Commands diff --git a/examples/cli/package.json b/examples/cli/package.json index d73b123..4c1622f 100644 --- a/examples/cli/package.json +++ b/examples/cli/package.json @@ -3,12 +3,12 @@ "private": true, "type": "module", "scripts": { - "dev": "markstage dev", - "build": "markstage build", - "preview": "markstage preview" + "dev": "mrp dev", + "build": "mrp build", + "preview": "mrp preview" }, "dependencies": { - "@izumisy/markstage": "workspace:*", + "@izumisy/md-react-preview": "workspace:*", "@tailor-platform/app-shell": "catalog:", "react": "catalog:", "react-dom": "catalog:" diff --git a/examples/cli/previewer.config.ts b/examples/cli/previewer.config.ts index 173d7e0..aa0b140 100644 --- a/examples/cli/previewer.config.ts +++ b/examples/cli/previewer.config.ts @@ -1,4 +1,4 @@ -import { defineConfig } from "@izumisy/markstage"; +import { defineConfig } from "@izumisy/md-react-preview"; export default defineConfig({ title: "AppShell docs", diff --git a/examples/vitepress/docs/.vitepress/config.ts b/examples/vitepress/docs/.vitepress/config.ts index bfd60c3..86efa25 100644 --- a/examples/vitepress/docs/.vitepress/config.ts +++ b/examples/vitepress/docs/.vitepress/config.ts @@ -1,13 +1,13 @@ import { defineConfig } from "vitepress"; -import { createMarkstagePlugin } from "@izumisy/vitepress-plugin-react-preview"; +import { createMrpPlugin } from "@izumisy/vitepress-plugin-react-preview"; -const markstage = createMarkstagePlugin({ +const mrp = createMrpPlugin({ css: "@tailor-platform/app-shell/styles", }); export default defineConfig({ title: "VitePress Example", - description: "Example of using Markstage preview blocks in VitePress", + description: "Example of using md-react-preview blocks in VitePress", themeConfig: { sidebar: [ @@ -26,11 +26,11 @@ export default defineConfig({ markdown: { config(md) { - md.use(markstage.markdownIt); + md.use(mrp.markdownIt); }, }, vite: { - plugins: [...markstage.vite()], + plugins: [...mrp.vite()], }, }); diff --git a/examples/vitepress/docs/index.md b/examples/vitepress/docs/index.md index 9da4cc7..3ae2531 100644 --- a/examples/vitepress/docs/index.md +++ b/examples/vitepress/docs/index.md @@ -1,7 +1,7 @@ --- layout: home hero: - name: "Markstage + VitePress" + name: "md-react-preview + VitePress" text: "React Component Preview Example" tagline: Live preview of React components inside VitePress using iframe isolation actions: diff --git a/package.json b/package.json index 3d863d6..c2f33da 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "markstage", + "name": "md-react-preview", "private": true, "packageManager": "pnpm@10.24.0", "engines": { diff --git a/packages/markstage/README.md b/packages/md-react-preview/README.md similarity index 87% rename from packages/markstage/README.md rename to packages/md-react-preview/README.md index 6ca71fe..c9225e8 100644 --- a/packages/markstage/README.md +++ b/packages/md-react-preview/README.md @@ -1,21 +1,21 @@ -# @izumisy/markstage +# @izumisy/md-react-preview -CLI and programmatic API for Markstage — a zero-config component previewer for React projects. +CLI and programmatic API for md-react-preview — a zero-config component previewer for React projects. Drop Markdown files into `docs/` with `` ```tsx preview `` fenced blocks and get a Vite-powered dev server with live component previews and syntax-highlighted source code. ## Install ```bash -pnpm add -D @izumisy/markstage +pnpm add -D @izumisy/md-react-preview ``` ## CLI ```bash -npx markstage dev # Start dev server (default port 3040) -npx markstage build # Build static output -npx markstage preview # Preview the production build locally +npx mrp dev # Start dev server (default port 3040) +npx mrp build # Build static output +npx mrp preview # Preview the production build locally ``` ## Writing Previews @@ -77,7 +77,7 @@ Options can be set as `key="value"` pairs or boolean flags in the fence meta: Create a `previewer.config.ts` at your project root: ```ts -import { defineConfig } from "@izumisy/markstage"; +import { defineConfig } from "@izumisy/md-react-preview"; export default defineConfig({ title: "My Component Library", @@ -99,7 +99,7 @@ export default defineConfig({ ## Programmatic API ```ts -import { startDev, runBuild, defineConfig, createPreviewerViteConfig } from "@izumisy/markstage"; +import { startDev, runBuild, defineConfig, createPreviewerViteConfig } from "@izumisy/md-react-preview"; ``` | Export | Description | diff --git a/packages/markstage/app/index.html b/packages/md-react-preview/app/index.html similarity index 96% rename from packages/markstage/app/index.html rename to packages/md-react-preview/app/index.html index caa4834..fa602e6 100644 --- a/packages/markstage/app/index.html +++ b/packages/md-react-preview/app/index.html @@ -3,7 +3,7 @@ - Markstage + md-react-preview