Skip to content

Commit 2d27389

Browse files
jaywcjlovejaywcjlove
committed
doc: add english document.
1 parent c47dfa0 commit 2d27389

File tree

3 files changed

+171
-20
lines changed

3 files changed

+171
-20
lines changed

‎core/README-zh.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
markdown-react-code-preview-loader
2+
===
3+
4+
索引 Markdown 中的示例文本，转换为 React 组件。当前包是 `webpack` 的 `loader`，通过配置当前 `loader` 加载 `markdown` 文档，返回一个 `JS` 对象，包含 `markdown` 文本，`markdown` 文本中的示例索引。
5+
6+
## 安装 Loader
7+
8+
```bash
9+
npm i markdown-react-code-preview-loader -D
10+
```
11+
12+
## 配置 Loader
13+
14+
安装依赖(loader)之后，我们需要将 `loader` 配置到 `webpack` 配置中，通过在 `kkt` 中两种配置方法，了解如何使用配置 `loader`。
15+
16+
**第 ① 种方法，使用 mdCodeModulesLoader 方法**
17+
18+
```ts
19+
// .kktrc.ts
20+
import scopePluginOptions from '@kkt/scope-plugin-options';
21+
import { LoaderConfOptions, WebpackConfiguration } from 'kkt';
22+
import { mdCodeModulesLoader } from 'markdown-react-code-preview-loader';
23+
24+
export default (conf: WebpackConfiguration, env: 'development' | 'production', options: LoaderConfOptions) => {
25+
// ....
26+
conf = mdCodeModulesLoader(conf);
27+
// ....
28+
return conf;
29+
};
30+
```
31+
32+
**第 ② 种方法，手动添加配置**
33+
34+
在 Webpack 中配置使用方法是一致的。
35+
36+
```ts
37+
// .kktrc.ts
38+
import webpack, { Configuration } from 'webpack';
39+
import scopePluginOptions from '@kkt/scope-plugin-options';
40+
import { LoaderConfOptions } from 'kkt';
41+
42+
export default (conf: Configuration, env: 'development' | 'production', options: LoaderConfOptions) => {
43+
// ....
44+
config.module.rules.forEach((ruleItem) => {
45+
if (typeof ruleItem === 'object') {
46+
if (ruleItem.oneOf) {
47+
ruleItem.oneOf.unshift({
48+
test: /.md$/,
49+
use: [
50+
{
51+
loader: 'markdown-react-code-preview-loader',
52+
options: { lang:["jsx","tsx"] },
53+
},
54+
],
55+
});
56+
}
57+
}
58+
});
59+
// ....
60+
return conf;
61+
};
62+
```
63+
64+
### options 参数
65+
66+
- lang: 需要解析代码块的语言，默认: `["jsx","tsx"]`
67+
68+
## 项目中使用
69+
70+
添加 `loader` 之后，在项目工程中加载 `markdown` 文本使用方法：
71+
72+
```jsx
73+
import mdObj from 'markdown-react-code-preview-loader/README.md';
74+
75+
mdObj.source // => `README.md` 原始字符串文本
76+
mdObj.components // => 组件索引对象，从 markdown 索引到的示例转换成的 React 组件。(需要配置 meta)
77+
mdObj.codeBlock // => 组件源码索引对象，从 markdown 索引到的示例源码。(需要配置 meta)
78+
```
79+
80+
```js
81+
{
82+
codeBlock: {
83+
17: 'import React from ...',
84+
77: 'import React from ...',
85+
base23: 'import React from ...'
86+
},
87+
components: { 17: ƒ, 77: ƒ, base23: ƒ },
88+
languages: { 17: 'jsx', 77: 'jsx', base23: 'jsx'},
89+
source: "# Alert 确认对话框...."
90+
}
91+
```
92+
93+
```ts
94+
export type CodeBlockData = {
95+
source: string;
96+
components: Record<string | number, React.FC>;
97+
codeBlock: Record<string | number, string>;
98+
languages: Record<string | number, string>;
99+
};
100+
```
101+
102+
## getCodeBlockString
103+
104+
传递 `markdown` 文件内容字符串，返回转换好的需要预览的代码块解析数据。
105+
106+
## 配置 meta 标识
107+
108+
注意：需要在代码块示例中添加特殊的 `meta` 标识，`loader` 才会去索引对于的 `react` 示例，进行代码转换。
109+
110+
1. `mdx:` 特殊标识前缀
111+
2. `mdx:preview` 控制是否进行进行示例索引，通过对应所在行号，获取需要的示例对象。
112+
3. `mdx:preview:demo12` 通过 `demo12` 唯一标识，准确获取索引的 `示例代码` 或 `示例组件对象`。
113+
114+
```markdown mdx:preview
115+
\```tsx
116+
import React from "react"
117+
const Demo = ()=>{
118+
return <div>测试</div>
119+
}
120+
121+
export default Demo
122+
\```
123+
124+
\```tsx mdx:preview:demo12
125+
import React from "react"
126+
const Demo = ()=>{
127+
return <div>测试</div>
128+
}
129+
130+
export default Demo
131+
\```
132+
```
133+
134+
## Development
135+
136+
```bash
137+
npm install # Install dependencies
138+
npm run hoist # Install sub packages dependencies
139+
140+
npm run watch:loader
141+
npm run start
142+
```
143+
### License
144+
145+
Licensed under the MIT License.

‎core/README.md

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
markdown-react-code-preview-loader
22
===
33

4-
当前包是 `webpack` 的 `loader`，通过配置当前 `loader` 加载 `markdown` 文档，返回一个 `JS` 对象，包含 `markdown` 文本，`markdown` 文本中的示例索引。
4+
Index example text in Markdown, converted to React components. The current package is the `loader` of `webpack`, which loads the `markdown` document by configuring the current `loader`, returning a `JS` object containing the `markdown` text, the example index in the `markdown` text.
55

6-
## 安装 Loader
6+
## Install Loader
77

88
```bash
99
npm i markdown-react-code-preview-loader -D
1010
```
1111

12-
## 配置 Loader
12+
## Configure Loader
1313

14-
安装依赖(loader)之后，我们需要将 `loader` 配置到 `webpack` 配置中，通过在 `kkt` 中两种配置方法，了解如何使用配置 `loader`。
14+
After installing the dependency (loader), we need to configure the `loader` into the `webpack` configuration. Learn how to use the configuration `loader` by using two configuration methods in `kkt`.
1515

16-
**第 ① 种方法，使用 mdCodeModulesLoader 方法**
16+
**① The first method, use the mdCodeModulesLoader method**
1717

1818
```ts
1919
// .kktrc.ts
@@ -29,7 +29,9 @@ export default (conf: WebpackConfiguration, env: 'development' | 'production', o
2929
};
3030
```
3131

32-
**第 ② 种方法，自己手动添加配置，在 Webpack 中配置使用方法是一样的**
32+
**② The second method is to manually add the configuration**
33+
34+
The configuration and usage methods are consistent in Webpack.
3335

3436
```ts
3537
// .kktrc.ts
@@ -59,20 +61,20 @@ export default (conf: Configuration, env: 'development' | 'production', options:
5961
};
6062
```
6163

62-
### options 参数
64+
### options parameter
6365

64-
- lang: 需要解析代码块的语言，默认: `["jsx","tsx"]`
66+
- lang: Language to parse code blocks, default: `["jsx","tsx"]`
6567

66-
## 使用
68+
## Used in the project
6769

68-
添加 `loader` 之后，在项目工程中加载 `markdown` 文本使用方法：
70+
After adding `loader`, use the method to load `markdown` text in the project project:
6971

7072
```jsx
7173
import mdObj from 'markdown-react-code-preview-loader/README.md';
7274

73-
mdObj.source // => `README.md` 原始字符串文本
74-
mdObj.components // => 组件索引对象，从 markdown 索引到的示例转换成的 React 组件。(需要配置 meta)
75-
mdObj.codeBlock // => 组件源码索引对象，从 markdown 索引到的示例源码。(需要配置 meta)
75+
mdObj.source // => `README.md` raw string text
76+
mdObj.components // => The component index object, the React component converted from the markdown indexed example. (need to configure meta)
77+
mdObj.codeBlock // => The component source code index object, the sample source code indexed from markdown. (need to configure meta)
7678
```
7779

7880
```js
@@ -99,15 +101,15 @@ export type CodeBlockData = {
99101

100102
## getCodeBlockString
101103

102-
传递 `markdown` 文件内容字符串，返回转换好的需要预览的代码块解析数据。
104+
Pass the `markdown` file content string, and return the converted code block parsing data that needs to be previewed.
103105

104-
## 配置 meta 标识
106+
## Configure meta ID
105107

106-
注意：需要在代码块示例中添加特殊的 `meta` 标识，`loader` 才会去索引对于的 `react` 示例，进行代码转换。
108+
Note: You need to add a special `meta` identifier to the code block example, and `loader` will index the `react` example for code conversion.
107109

108-
1. `mdx:` 特殊标识前缀
109-
2. `mdx:preview` 控制是否进行进行示例索引，通过对应所在行号，获取需要的示例对象。
110-
3. `mdx:preview:demo12` 通过 `demo12` 唯一标识，准确获取索引的 `示例代码` 或 `示例组件对象`。
110+
1. `mdx:` special identifier prefix
111+
2. `mdx:preview` Controls whether to perform example indexing, and obtain the required example object through the corresponding line number.
112+
3. `mdx:preview:demo12` Uniquely identified by `demo12`, accurately obtain the `example code` or `example component object` of the index.
111113

112114
```markdown mdx:preview
113115
\```tsx

‎core/package.json

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@
22
"$schema": "https://json.schemastore.org/package.json",
33
"name": "markdown-react-code-preview-loader",
44
"version": "1.0.0",
5-
"description": "解析 markdown 预览代码块，转换成可预览的内容",
5+
"description": "Index react example text in markdown, converted to React components.",
66
"author": "SunLxy <1011771396@qq.com>",
7+
"contributors": [
8+
"SunLxy <1011771396@qq.com>",
9+
"Kenny Wong <wowohoo@qq.com>"
10+
],
711
"license": "MIT",
812
"main": "./lib/index.js",
913
"module": "esm/index.js",

0 commit comments

Comments
 (0)