From f23254c64861683d5b1781607fcf8d663ac7016a Mon Sep 17 00:00:00 2001 From: simonguo Date: Sun, 4 Jan 2026 11:12:35 +0800 Subject: [PATCH] docs: fix code-documentation inconsistencies - Fix core/README.md: replace non-existent registerLanguage with actual initHighlighter API - Remove highlight.css references: Shiki themes are controlled via props, not separate CSS imports - Update all CHANGELOG files to remove outdated highlight.css references - Clarify that highlight() is async and returns a Promise - Update migration guide to reflect actual v3 API --- README.md | 2 +- RELEASE_NOTES_v3.0.0.md | 84 --------------------------- examples/vite/src/docs/example.md | 0 examples/vite/src/test-parse.js | 0 packages/core/CHANGELOG.md | 2 +- packages/core/README.md | 17 ++++-- packages/react-code-view/CHANGELOG.md | 2 +- packages/react-code-view/README.md | 3 +- packages/react/CHANGELOG.md | 2 +- packages/unplugin/CHANGELOG.md | 2 +- 10 files changed, 17 insertions(+), 97 deletions(-) delete mode 100644 RELEASE_NOTES_v3.0.0.md create mode 100644 examples/vite/src/docs/example.md create mode 100644 examples/vite/src/test-parse.js diff --git a/README.md b/README.md index 88293ba..09c3032 100644 --- a/README.md +++ b/README.md @@ -362,7 +362,7 @@ Major changes in v3.0.0 modernize the architecture and usage. Here’s how to up - After (v3): `import CodeView from 'react-code-view'` or `import { CodeView } from '@react-code-view/react'` - Styles: Use the new CSS entry points. - Before (v2): Less files (e.g., `react-code-view/less/styles.less`) - - After (v3): `import 'react-code-view/styles'` and optional syntax theme `import 'react-code-view/styles/highlight'` + - After (v3): `import 'react-code-view/styles'` - Build tool integration: Replace legacy Webpack markdown loader with the unified unplugin across tools. - Before (v2): `webpack-md-loader` and custom loader config - After (v3): `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack (see examples above) diff --git a/RELEASE_NOTES_v3.0.0.md b/RELEASE_NOTES_v3.0.0.md deleted file mode 100644 index 9257249..0000000 --- a/RELEASE_NOTES_v3.0.0.md +++ /dev/null @@ -1,84 +0,0 @@ -# Release Notes — v3.0.0 (2025-12-29) - -A major overhaul that migrates `react-code-view` into a PNPM/Turbo monorepo, unifies build integrations, and refreshes the API/docs. This release is **breaking** compared to 2.6.1. Usage examples below follow the latest README/docs. - -## Highlights -- Monorepo migration with PNPM + Turbo; updated CI (Node 18+, caching, docs from `docs/dist`). -- Unified build plugin: new `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack. -- Imports simplified: `CodeView` is the default export from `@react-code-view/react`; re-exported via `react-code-view` if needed. -- Styles streamlined: use `import '@react-code-view/react/styles/index.css'` (CSS). Legacy Less entries removed. -- `useCodeExecution` stabilized: stable `execute` ref and `updateCode` alias; hook examples refreshed. -- Docs rewritten (installation, usage, migration) and Changesets added for versioning. - -## Breaking Changes -- **Tooling requirements:** Node >= 18, PNPM >= 8 (dev workflow). Update CI to match. -- **Imports:** Prefer `import CodeView from 'react-code-view'`; adjust named imports if you targeted old paths. -- **Styles:** Switch to CSS entries: `import 'react-code-view/styles'` (or specific CSS files). Remove Less imports. -- **Build integration:** Legacy `webpack-md-loader` removed. Use the unified unplugin instead. - -## Migration Guide (v2.6.1 → v3.0.0) -Use `@react-code-view/react` as the primary entry and the new unplugin across bundlers. - -1) **Install** - ```bash - pnpm add @react-code-view/react @react-code-view/unplugin - ``` - -2) **Imports** - ```tsx - import CodeView from '@react-code-view/react'; - import { Renderer, MarkdownRenderer } from '@react-code-view/react'; - // (Optional) re-exported convenience: - // import CodeView from 'react-code-view'; - ``` - -3) **Styles (CSS)** - ```tsx - import '@react-code-view/react/styles/index.css'; - ``` - -4) **Build plugin (Vite example)** - ```js - // vite.config.js - import { defineConfig } from 'vite'; - import react from '@vitejs/plugin-react'; - import reactCodeView from '@react-code-view/unplugin/vite'; - - export default defineConfig({ - plugins: [react(), reactCodeView()] - }); - ``` - Webpack: `@react-code-view/unplugin/webpack` - Rollup: `@react-code-view/unplugin/rollup` - esbuild: `@react-code-view/unplugin/esbuild` - Rspack: `@react-code-view/unplugin/rspack` - -5) **Hook usage (`useCodeExecution`)** - ```tsx - import { useCodeExecution } from '@react-code-view/react'; - - const { element, error, code, updateCode, execute } = useCodeExecution( - initialCode, - { - dependencies: { Button }, - transformOptions: { transforms: ['typescript', 'jsx'] }, - beforeCompile: (c) => c.trim(), - afterCompile: (c) => c, - onError: (e) => console.error('Execution error:', e) - } - ); - ``` - -6) **Remove legacy `webpack-md-loader`** - - Replace with the unified unplugin (see entries above). - -## Feature Details -- Monorepo structure with Changesets-driven versioning and consistent lint/format configs. -- `useCodeExecution` stability improvements and docs examples (matches latest README snippets). -- README/docs updated for new package layout, usage, and migration steps. -- CI updated to use PNPM via Corepack; gh-pages publishes `docs/dist`. - -## Links -- PR: https://github.com/simonguo/react-code-view/pull/59 -- npm v3.0.0: https://www.npmjs.com/package/react-code-view/v/3.0.0 -- v2.6.1 (previous): https://www.npmjs.com/package/react-code-view/v/2.6.1 diff --git a/examples/vite/src/docs/example.md b/examples/vite/src/docs/example.md new file mode 100644 index 0000000..e69de29 diff --git a/examples/vite/src/test-parse.js b/examples/vite/src/test-parse.js new file mode 100644 index 0000000..e69de29 diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md index d19f4ba..916528b 100644 --- a/packages/core/CHANGELOG.md +++ b/packages/core/CHANGELOG.md @@ -16,6 +16,6 @@ - `useCodeExecution` effect behavior stabilized; consumers relying on previous implicit re-execution may need to explicitly update `code` or pass `dependencies` - Package structure reorganized across `packages/*`; import paths may need updates according to exports - Imports: `CodeView` is now also a default export in `@react-code-view/react` and re-exported by `react-code-view`; prefer `import CodeView from 'react-code-view'` or adjust named imports accordingly - - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` and optional `import 'react-code-view/styles/highlight'` + - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` - Build integration: Legacy `webpack-md-loader` is removed; migrate to unified `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack - Tooling: Minimum requirements updated to Node >=18 and PNPM >=8 for the monorepo/dev workflow diff --git a/packages/core/README.md b/packages/core/README.md index cd5d852..9b779d9 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -41,11 +41,12 @@ const result = await transformMarkdown(markdown, { ### Direct Highlighting ```js -import { highlight, registerLanguage } from '@react-code-view/core'; +import { highlight, initHighlighter } from '@react-code-view/core'; -await registerLanguage('python'); +// Initialize highlighter (optional, will auto-initialize on first use) +await initHighlighter(); -const highlighted = highlight('print("Hello")', { language: 'python' }); +const highlighted = await highlight('print("Hello")', { language: 'python' }); ``` ## API @@ -61,11 +62,15 @@ Transform markdown to an ES module string. ### `highlight(code, options?)` -Highlight code with syntax highlighting. +Highlight code with syntax highlighting using Shiki. -### `registerLanguage(name)` +**Options:** +- `language` - Programming language (e.g., 'javascript', 'python') +- `theme` - Shiki theme (default: 'github-light') + +### `initHighlighter()` -Register a language for highlighting. +Initialize the Shiki highlighter. Called automatically on first use. ## License diff --git a/packages/react-code-view/CHANGELOG.md b/packages/react-code-view/CHANGELOG.md index c2c86c3..d2ebbfd 100644 --- a/packages/react-code-view/CHANGELOG.md +++ b/packages/react-code-view/CHANGELOG.md @@ -16,7 +16,7 @@ - `useCodeExecution` effect behavior stabilized; consumers relying on previous implicit re-execution may need to explicitly update `code` or pass `dependencies` - Package structure reorganized across `packages/*`; import paths may need updates according to exports - Imports: `CodeView` is now also a default export in `@react-code-view/react` and re-exported by `react-code-view`; prefer `import CodeView from 'react-code-view'` or adjust named imports accordingly - - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` and optional `import 'react-code-view/styles/highlight'` + - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` - Build integration: Legacy `webpack-md-loader` is removed; migrate to unified `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack - Tooling: Minimum requirements updated to Node >=18 and PNPM >=8 for the monorepo/dev workflow diff --git a/packages/react-code-view/README.md b/packages/react-code-view/README.md index e976c68..bd7db1f 100644 --- a/packages/react-code-view/README.md +++ b/packages/react-code-view/README.md @@ -145,9 +145,8 @@ Import the base styles: ```tsx import 'react-code-view/styles'; -// or specific files +// or import 'react-code-view/styles/index.css'; -import 'react-code-view/styles/highlight.css'; ``` Use theme classes: diff --git a/packages/react/CHANGELOG.md b/packages/react/CHANGELOG.md index 818807c..aec0531 100644 --- a/packages/react/CHANGELOG.md +++ b/packages/react/CHANGELOG.md @@ -16,7 +16,7 @@ - `useCodeExecution` effect behavior stabilized; consumers relying on previous implicit re-execution may need to explicitly update `code` or pass `dependencies` - Package structure reorganized across `packages/*`; import paths may need updates according to exports - Imports: `CodeView` is now also a default export in `@react-code-view/react` and re-exported by `react-code-view`; prefer `import CodeView from 'react-code-view'` or adjust named imports accordingly - - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` and optional `import 'react-code-view/styles/highlight'` + - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` - Build integration: Legacy `webpack-md-loader` is removed; migrate to unified `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack - Tooling: Minimum requirements updated to Node >=18 and PNPM >=8 for the monorepo/dev workflow diff --git a/packages/unplugin/CHANGELOG.md b/packages/unplugin/CHANGELOG.md index 6958bd9..b3601bd 100644 --- a/packages/unplugin/CHANGELOG.md +++ b/packages/unplugin/CHANGELOG.md @@ -16,7 +16,7 @@ - `useCodeExecution` effect behavior stabilized; consumers relying on previous implicit re-execution may need to explicitly update `code` or pass `dependencies` - Package structure reorganized across `packages/*`; import paths may need updates according to exports - Imports: `CodeView` is now also a default export in `@react-code-view/react` and re-exported by `react-code-view`; prefer `import CodeView from 'react-code-view'` or adjust named imports accordingly - - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` and optional `import 'react-code-view/styles/highlight'` + - Styles: Less entries were removed; switch to `import 'react-code-view/styles'` - Build integration: Legacy `webpack-md-loader` is removed; migrate to unified `@react-code-view/unplugin` for Vite/Webpack/Rollup/esbuild/Rspack - Tooling: Minimum requirements updated to Node >=18 and PNPM >=8 for the monorepo/dev workflow