diff --git a/.gitignore b/.gitignore index ee5fc599..73a32bea 100644 --- a/.gitignore +++ b/.gitignore @@ -43,5 +43,6 @@ logs # Comark packages/comark/skills +packages/comark/src/devtools/renderer/styles.ts .vercel .env* diff --git a/AGENTS.md b/AGENTS.md index 10b275e5..88b84159 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,22 @@ packages/comark/ │ │ ├── index.ts # Re-exports (comark/ast entry point) │ │ ├── types.ts # ComarkTree, ComarkNode, ComarkElement, ComarkText │ │ └── utils.ts # textContent(), visit() tree utilities +│ ├── devtools/ # Vite DevTools integration +│ │ ├── index.ts # Public exports (comark/devtools entry point) +│ │ ├── bridge.ts # Context ↔ HMR bridge for the Vite DevTools panel +│ │ ├── client.ts # Injected client entry (connectDevtools) +│ │ ├── vite.ts # Vite plugin with RPC endpoints (comark/devtools/vite entry point) +│ │ ├── renderer.ts # Re-export barrel (comark/devtools/renderer entry point) +│ │ ├── types.ts # Shared TypeScript interfaces for RPC and panel +│ │ ├── constants.ts # Icon assets and Shiki theme/lang config +│ │ └── renderer/ # DevTools panel UI (internal) +│ │ ├── index.ts # Entry point, exports DevtoolsPanel +│ │ ├── panel.ts # Panel class: tabs, editor, polling, RPC orchestration +│ │ ├── dom.ts # DOM element factories (editor, tab bar, states) +│ │ ├── output.ts # AST rendering, regex fallback highlighter +│ │ ├── styles.ts # CSS styles (imports styles.css) +│ │ ├── styles.css # Panel stylesheet +│ │ └── theme.ts # Light/dark/auto theme toggle │ ├── plugins/ # Built-in and optional plugins │ │ ├── alert.ts # Alert/callout blocks │ │ ├── emoji.ts # Emoji shortcodes @@ -76,9 +92,10 @@ packages/comark/ | Peer | Required by | |------|-------------| -| `shiki` | `comark/plugins/highlight` | +| `shiki` | `comark/plugins/highlight`, `comark/devtools/vite` (devtools Shiki highlighting) | | `katex` | `comark/plugins/math` | | `beautiful-mermaid` | `comark/plugins/mermaid` | +| `@vitejs/devtools-kit` | `comark/devtools/vite` (Vite DevTools integration) | All are optional — only install what you use. @@ -380,6 +397,13 @@ import emoji from 'comark/plugins/emoji' import toc from 'comark/plugins/toc' import alert from 'comark/plugins/alert' +// Vite DevTools integration +import { comarkDevtools } from 'comark/devtools/vite' +// Ambient live-document context (used by renderers via comarkKey) +import { createComarkContext } from 'comark' +// Optional: manual bridge connect (normally injected by comarkDevtools()) +import { connectDevtools } from 'comark/devtools' + // NOTE: All framework packages re-export every core plugin via their own subpath. // Prefer the framework-specific path when using a framework renderer: // @comark/vue/plugins/highlight, @comark/react/plugins/highlight, etc. @@ -402,7 +426,7 @@ import math, { Math } from '@comark/vue/plugins/math' import mermaid, { Mermaid } from '@comark/vue/plugins/mermaid' // React — renderer + plugin wrappers (plugin fn + React component) -import { Comark, ComarkRenderer, defineComarkComponent } from '@comark/react' +import { Comark, ComarkServer, ComarkClient, ComarkRenderer, defineComarkComponent } from '@comark/react' import math, { Math } from '@comark/react/plugins/math' import mermaid, { Mermaid } from '@comark/react/plugins/mermaid' diff --git a/docs/content/3.rendering/5.react.md b/docs/content/3.rendering/5.react.md index c1d2dbb9..1dbec5b2 100644 --- a/docs/content/3.rendering/5.react.md +++ b/docs/content/3.rendering/5.react.md @@ -43,10 +43,10 @@ bun add @comark/react ## `` -The `` component is the simplest way to render markdown in React. It handles parsing and rendering automatically. +The `` component is the simplest way to render markdown in React. It handles parsing and rendering automatically, and works in both client-side (Vite, CRA) and server-side (Next.js) contexts. -::warning{to="#code-comarkrenderer"} -`` is an **async** component. You can also use the `` component to handle parsing yourself. +::info +For React Server Components (Next.js `app/` directory), you can also use [``](#code-comarkserver) to parse markdown on the server with `await`. :: ```tsx [App.tsx] @@ -371,6 +371,29 @@ export default async function Page({ params }: { params: { slug: string } }) { --- +## `` + +Async server-only component that parses markdown on the server using `await`. Only works in React Server Components (Next.js `app/` directory). For client-side usage, use [``](#code-comark). + +Accepts the same props as ``. When `streaming` is true, it delegates to the client-side ``. + +```tsx [app/docs/[slug]/page.tsx] +import { ComarkServer } from '@comark/react' +import Alert from '@/components/Alert' + +export default async function Page({ params }: { params: { slug: string } }) { + const content = await getDocContent(params.slug) + + return {content} +} +``` + +::warning +`` is an `async` function component and will throw in client-only environments (Vite, CRA). Use `` instead for universal usage. +:: + +--- + ## `` Renders a pre-parsed `ComarkTree` without any parsing. Use it when you parse on the server, in a build step, or via an API, so no parser or plugin code is shipped to the browser. diff --git a/docs/content/7.kb/5.devtools.md b/docs/content/7.kb/5.devtools.md new file mode 100644 index 00000000..06f9bf33 --- /dev/null +++ b/docs/content/7.kb/5.devtools.md @@ -0,0 +1,130 @@ +--- +title: Vite DevTools +description: Interactive Comark playground panel inside Vite DevTools for real-time markdown editing and AST inspection. +seo: + title: Vite DevTools Integration +navigation: + icon: i-lucide-wrench +links: + - label: Vite DevTools + icon: i-lucide-external-link + to: https://devtools.vite.dev/ + color: neutral + variant: soft +--- + +Comark integrates with [Vite DevTools](https://devtools.vite.dev/) to provide an interactive playground panel for real-time markdown editing and AST inspection. This is a development tool that uses the Vite dev server's HMR and RPC capabilities. + +## Setup + +Install the `@vitejs/devtools` peer dependency alongside `comark`: + +::code-group + +```bash [pnpm] +pnpm add -D @vitejs/devtools +``` + +```bash [npm] +npm install -D @vitejs/devtools +``` + +```bash [yarn] +yarn add -D @vitejs/devtools +``` + +:: + +Add both plugins to your Vite config: + +```ts [vite.config.ts] +import { defineConfig } from 'vite' +import { DevTools } from '@vitejs/devtools' +import { comarkDevtools } from 'comark/devtools/vite' + +export default defineConfig({ + plugins: [ + DevTools(), + comarkDevtools(), + ], +}) +``` + +> [!TIP] +> If you use `@comark/vue`, its Vite plugin already includes `comarkDevtools()` automatically - no extra config needed: +> ```ts [vite.config.ts] +> import { defineConfig } from 'vite' +> import vue from '@vitejs/plugin-vue' +> import { DevTools } from '@vitejs/devtools' +> import comark from '@comark/vue/vite' +> +> export default defineConfig({ +> plugins: [vue(), DevTools(), comark()], +> }) +> ``` + +## Features + +### Markdown Editor + +The panel includes a markdown editor with [Shiki](https://shiki.style/)-powered syntax highlighting using the `mdc` grammar. A transparent `