Skip to content

Commit 48803eb

Browse files
makhnatkinmakhnatkin
authored
docs: added docs about extensions (#308)
* fix(docs): added docs about extensions
1 parent 05c363b commit 48803eb

7 files changed

+718
-1
lines changed

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,16 @@ function Editor({onSubmit}) {
4646
};
4747
}, [onSubmit]);
4848

49-
return <MarkdownEditorView autofocus toaster={toaster} editor={editor} />;
49+
return <MarkdownEditorView stickyToolbar autofocus toaster={toaster} editor={editor} />;
5050
}
5151
```
52+
Read more:
53+
- [How to connect the editor in the Create React App](docs/how-to-add-editor-with-create-react-app.md)
54+
- [How to add preview for markup mode](docs/how-to-add-preview.md)
55+
- [How to add HTML extension](docs/how-to-connect-html-extension.md)
56+
- [How to add Latex extension](docs/how-to-connect-latex-extension.md)
57+
- [How to add Mermaid extension](docs/how-to-connect-mermaid-extension.md)
58+
- [How to write extension](docs/how-to-create-extension.md)
5259

5360
### i18n
5461

‎docs/how-to-add-editor-with-create-react-app.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
## Installation Guide
2+
3+
### 1. Setting Up the Environment for the React Application
4+
First, set up the environment for React. In this example, we will use Create React App:
5+
6+
```bash
7+
npx create-react-app markdown-editor --template typescript
8+
cd markdown-editor
9+
```
10+
11+
### 2. Installing the Markdown editor
12+
Install the Markdown editor
13+
14+
```bash
15+
npm install @gravity-ui/markdown-editor
16+
```
17+
18+
### 3. Installing dependencies
19+
Ensure that you have the necessary dependencies listed in peerDependencies. Include the following packages:
20+
- `@diplodoc/transform`
21+
- `react`
22+
- `react-dom`
23+
- `@gravity-ui/uikit`
24+
- `@gravity-ui/components`
25+
26+
Check the peerDependencies section in the `package.json` file to ensure all necessary dependencies are installed correctly.
27+
28+
To install the dependencies, use:
29+
30+
```bash
31+
npm install @diplodoc/transform react react-dom @gravity-ui/uikit @gravity-ui/components
32+
```
33+
34+
### 4. Configuring Webpack
35+
In order for the `diplodoc/transform` process to function correctly, please add the [webpack resolve-fallbacks](https://webpack.js.org/configuration/resolve/#resolvefallback).
36+
37+
To accomplish this, please install CRACO and configure it follow the instructions below:
38+
39+
1. Install CRACO:
40+
41+
```bash
42+
npm install @craco/craco
43+
```
44+
2. Create a file called craco.config.js in the root of the project and add the following configuration:
45+
46+
```javascript
47+
module.exports = {
48+
webpack: {
49+
configure: (webpackConfig) => {
50+
webpackConfig.resolve.fallback = {
51+
fs: false,
52+
process: false,
53+
path: false,
54+
};
55+
return webpackConfig;
56+
},
57+
},
58+
};
59+
```
60+
3. Update package.json to use craco for scripts:
61+
62+
```json
63+
{
64+
"scripts": {
65+
"start": "craco start",
66+
"build": "craco build",
67+
"test": "craco test",
68+
"eject": "react-scripts eject"
69+
}
70+
}
71+
```
72+
### 5. Configuring the application
73+
Add ThemeProvider to App:
74+
75+
```ts
76+
import { ThemeProvider } from '@gravity-ui/uikit';
77+
78+
// ...
79+
function App() {
80+
return (
81+
<ThemeProvider theme="light">
82+
<Editor onSubmit={(value) => console.log(value)} />
83+
</ThemeProvider>
84+
);
85+
}
86+
```
87+
Add the Editor component to App:
88+
89+
```ts
90+
import React from 'react';
91+
import { useMarkdownEditor, MarkdownEditorView } from '@gravity-ui/markdown-editor';
92+
import { toaster } from '@gravity-ui/uikit/toaster-singleton-react-18';
93+
94+
function Editor({ onSubmit }) {
95+
const editor = useMarkdownEditor({ allowHTML: false });
96+
97+
React.useEffect(() => {
98+
function submitHandler() {
99+
// Serialize current content to markdown markup
100+
const value = editor.getValue();
101+
onSubmit(value);
102+
}
103+
104+
editor.on('submit', submitHandler);
105+
return () => {
106+
editor.off('submit', submitHandler);
107+
};
108+
}, [onSubmit]);
109+
110+
return <MarkdownEditorView stickyToolbar autofocus toaster={toaster} editor={editor} />;
111+
}
112+
```
113+
Add styles:
114+
115+
```ts
116+
import '@gravity-ui/uikit/styles/styles.css';
117+
```

‎docs/how-to-add-preview.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
## How to Add Preview for Markup Mode
2+
3+
### Add a Preview component
4+
5+
You can create your own component or use the component `YfmStaticView` that [provides the editor bundle](https://github.com/gravity-ui/markdown-editor/blob/main/src/view/components/YfmHtml/YfmStaticView.tsx)
6+
7+
### Add a handler for re-renders
8+
9+
```ts
10+
const {plugins, getValue, allowHTML, breaks, linkify, linkifyTlds, needToSanitizeHtml} = props;
11+
const [html, setHtml] = useState('');
12+
const [meta, setMeta] = useState<object | undefined>({});
13+
const divRef = useRef<HTMLDivElement>(null);
14+
15+
const theme = useThemeValue();
16+
17+
const render = useMemo(
18+
() =>
19+
debounce(() => {
20+
const res = transform(getValue(), {
21+
allowHTML,
22+
breaks,
23+
plugins,
24+
linkify,
25+
linkifyTlds,
26+
needToSanitizeHtml,
27+
}).result;
28+
setHtml(res.html);
29+
setMeta(res.meta);
30+
}, 200),
31+
[getValue, allowHTML, breaks, plugins, linkify, linkifyTlds, needToSanitizeHtml, theme],
32+
);
33+
34+
useEffect(() => {
35+
render();
36+
}, [props, render]);
37+
38+
return (
39+
<YfmStaticView
40+
ref={divRef}
41+
html={html}
42+
noListReset
43+
className="demo-preview"
44+
/>
45+
);
46+
};
47+
```
48+
### Pass additional properties to useMarkdownEditor
49+
50+
```ts
51+
// ...
52+
const renderPreview = useCallback<RenderPreview>(
53+
({getValue}) => (
54+
<SplitModePreview
55+
getValue={getValue}
56+
/>
57+
),
58+
[],
59+
);
60+
61+
const editor = useMarkdownEditor({allowHTML: false,
62+
renderPreview,
63+
initialEditorMode: 'wysiwyg',
64+
initialSplitModeEnabled: true,
65+
initialToolbarVisible: true,
66+
splitMode: 'horizontal',
67+
68+
});
69+
// ...
70+
```

‎docs/how-to-connect-html-extension.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
## How to Connect the HTML Extensions in the Editor
2+
3+
To integrate the HTML extensions in your editor, you will use the specified versions of the necessary packages. Here’s a detailed guide:
4+
5+
First to integrate this extension, you need to use the following versions of the packages:
6+
7+
- @gravity-ui/markdown-editor version 13.4.0 or higher
8+
- @diplodoc/html-extension version 1.2.7 or higher
9+
10+
## Usage
11+
12+
### 1. Install the Packages
13+
14+
First, ensure that you have all the necessary packages installed. You can use npm or yarn to add them to your project:
15+
16+
```bash
17+
npm install @gravity-ui/markdown-editor@^13.4.0
18+
npm install @diplodoc/html-extension@^1.2.7
19+
```
20+
21+
22+
### 2. Integrate the Plugin in the Transformer
23+
24+
You will need to import and configure the transformers in your editor setup. Below is an example of how to do this:
25+
26+
```typescript
27+
import { transform as transformHTML } from '@diplodoc/html-extension';
28+
29+
// Define the runtime marker constant
30+
const HTML_RUNTIME = 'html-runtime';
31+
32+
// Configure the plugins in your transformer setup
33+
const plugins: PluginWithParams[] = [
34+
// Add HTML transformer plugin
35+
transformHTML({ bundle: false, runtimeJsPath: HTML_RUNTIME }),
36+
37+
// Add other plugins as needed
38+
];
39+
```
40+
41+
### 3. Integrate into Editor
42+
43+
Ensure that these plugins are integrated into your editor's initialization or configuration file. Below is a simplified example to illustrate how you might set them up with a markdown editor:
44+
45+
```ts
46+
const editor = new MarkdownEditor({
47+
// Editor configuration
48+
plugins,
49+
// Other configurations
50+
});
51+
```
52+
53+
### 4. Adding a Higher-Order Component (HOC) in Static Render to Load Runtime and Apply Styling Hooks
54+
55+
```ts
56+
import {useEffect} from 'react';
57+
58+
import {YfmHtml} from '@gravity-ui/markdown-editor/view/components/YfmHtml';
59+
import type {WithYfmHtmlBlockProps} from '@gravity-ui/markdown-editor/view/hocs/withYfmHtml';
60+
import {withYfmHtmlBlock} from '@gravity-ui/markdown-editor/view/hocs/withYfmHtml';
61+
import {useEffect, useState} from 'react';
62+
63+
import {IHTMLIFrameElementConfig} from '@diplodoc/html-extension/runtime';
64+
import {getYfmHtmlBlockCssVariables} from '@gravity-ui/markdown-editor/view/hocs/withYfmHtml/utils';
65+
import {useThemeValue} from '@gravity-ui/uikit';
66+
67+
// HOC
68+
export const YFM_HTML_BLOCK_RUNTIME = 'yfm-html-block';
69+
70+
const YfmStaticView = withYfmHtmlBlock({runtime: YFM_HTML_BLOCK_RUNTIME})(YfmHtml);
71+
72+
const variablesMapping = {
73+
colorBackground: '--g-color-base-background',
74+
colorTextPrimary: '--g-color-text-primary',
75+
colorTextSecondary: '--g-color-text-secondary',
76+
fontFamily: '--g-font-family-sans',
77+
fontSize: '--g-text-body-1-font-size',
78+
};
79+
80+
// hooks
81+
export const useYfmHtmlBlockStyles = () => {
82+
const theme = useThemeValue();
83+
const [config, setConfig] = useState<IHTMLIFrameElementConfig | undefined>();
84+
85+
useEffect(() => {
86+
const bodyStyles = window.getComputedStyle(document.body);
87+
88+
const styles = Object.entries(variablesMapping).reduce(
89+
(acc, [key, cssVariable]) => {
90+
acc[key] = bodyStyles.getPropertyValue(cssVariable);
91+
return acc;
92+
},
93+
{} as Record<string, string>,
94+
);
95+
96+
setConfig({
97+
styles: getYfmHtmlBlockCssVariables(styles),
98+
classNames: [theme],
99+
resizePadding: 50,
100+
resizeDelay: 100,
101+
});
102+
}, [theme]);
103+
104+
return config;
105+
};
106+
107+
// render
108+
const HtmlRenderer = React.forwardRef<HTMLDivElement, HtmlRendererProps>((props, ref) => {
109+
// ...
110+
const theme = useThemeType(); // your hook for get theme
111+
112+
const yfmHtmlBlockConfig = useYfmHtmlBlockStyles();
113+
() => ({
114+
theme,
115+
zoom: {showMenu: true, bindKeys: true, resetOnBlur: true},
116+
}),
117+
[theme],
118+
);
119+
120+
// ...
121+
return (
122+
<div>
123+
<YfmStaticView
124+
html={html}
125+
meta={meta}
126+
ref={elementRef}
127+
yfmHtmlBlockConfig={yfmHtmlBlockConfig}
128+
/>
129+
{props.children}
130+
</div>
131+
);
132+
});
133+
134+
```
135+
136+
137+
### 5. Integrate the WYSiWYG Extension
138+
139+
```ts
140+
import {YfmHtmlBlock} from '@gravity-ui/markdown-editor/extensions/yfm/YfmHtmlBlock';
141+
142+
// ...
143+
builder.use(YfmHtmlBlock, { useConfig: useYfmHtmlBlockStyles });
144+
145+
```
146+
147+
### 5. Add Buttons to the Toolbar
148+
149+
```ts
150+
import {
151+
mYfmHtmlBlockButton,
152+
} from '@gravity-ui/markdown-editor/bundle/config/markup';
153+
154+
import {
155+
wYfmHtmlBlockItemData,
156+
} from '@gravity-ui/markdown-editor';
157+
158+
// add to useMarkdownEditor
159+
const mdEditor = useMarkdownEditor({
160+
// ...
161+
extensionOptions: {
162+
commandMenu: {actions: [wYfmHtmlBlockItemData]},
163+
},
164+
});
165+
166+
```
167+

0 commit comments

Comments
 (0)