@aiursoft/uistack-markdown-ui 1.2.24 → 1.2.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,31 +1,234 @@
|
|
|
1
|
-
|
|
1
|
+
<a name="markdownuijs"></a>
|
|
2
|
+
|
|
3
|
+
# Aiursoft MarkdownUI.js
|
|
2
4
|
|
|
3
5
|
[](https://gitlab.aiursoft.com/aiursoft/MarkdownUI.js/-/pipelines) [](https://www.npmjs.com/package/@aiursoft/uistack-markdown-ui)
|
|
4
6
|
|
|
5
7
|
Shared Markdown rendering, editing and reading components.
|
|
6
8
|
|
|
7
|
-
##
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
### What is MarkdownUI.js?
|
|
12
|
+
|
|
13
|
+
Shared Markdown rendering, editing and reading components.
|
|
14
|
+
|
|
15
|
+
<a name="install"></a>
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
Install the package in your project:
|
|
8
20
|
|
|
9
21
|
```bash
|
|
10
22
|
npm install @aiursoft/uistack-markdown-ui
|
|
11
23
|
```
|
|
12
24
|
|
|
25
|
+
The package provides ESM, CommonJS, TypeScript declarations and a browser IIFE build (`AiursoftMarkdownUi`). Browser editing and reading require the DOM; `renderMarkdown` can also be used from a Node.js module. Monaco, Mermaid and MathJax are supplied by the application when those integrations are needed.
|
|
26
|
+
|
|
13
27
|
## Usage
|
|
14
28
|
|
|
29
|
+
Save the following as `index.html` beside `node_modules/` and serve that directory over HTTP with your existing static-file server:
|
|
30
|
+
|
|
31
|
+
```html
|
|
32
|
+
<!doctype html>
|
|
33
|
+
<html lang="en">
|
|
34
|
+
<meta charset="utf-8">
|
|
35
|
+
<title>MarkdownUI example</title>
|
|
36
|
+
<body>
|
|
37
|
+
<div id="preview"></div>
|
|
38
|
+
<script src="./node_modules/@aiursoft/uistack-markdown-ui/dist/index.global.js"></script>
|
|
39
|
+
<script>
|
|
40
|
+
const preview = document.getElementById('preview');
|
|
41
|
+
preview.innerHTML = AiursoftMarkdownUi.renderMarkdown('# Hello');
|
|
42
|
+
</script>
|
|
43
|
+
</body>
|
|
44
|
+
</html>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Bundler import**
|
|
48
|
+
|
|
49
|
+
In an application bundle, create or select the preview element before assigning the rendered HTML:
|
|
50
|
+
|
|
15
51
|
```js
|
|
16
52
|
import { renderMarkdown } from '@aiursoft/uistack-markdown-ui';
|
|
17
53
|
|
|
54
|
+
const preview = document.getElementById('preview');
|
|
18
55
|
preview.innerHTML = renderMarkdown('# Hello');
|
|
19
56
|
```
|
|
20
57
|
|
|
21
58
|
See [usage and API](docs/usage.md) for editors, readers, image uploads and print integration.
|
|
22
59
|
|
|
60
|
+
### Complete Markdown editor
|
|
61
|
+
|
|
62
|
+
`createMarkdownEditor` owns the common editor behavior while the application remains
|
|
63
|
+
responsible for loading Monaco. Passing a loader instead of importing Monaco keeps it
|
|
64
|
+
out of application bundles and works with the standard Monaco AMD loader.
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
import { createMarkdownEditor, loadMonacoFromAmd } from "@aiursoft/uistack-markdown-ui";
|
|
68
|
+
|
|
69
|
+
const markdownEditor = await createMarkdownEditor({
|
|
70
|
+
editorContainer: document.querySelector("#markdown-editor"),
|
|
71
|
+
textarea: document.querySelector("#markdown-source"),
|
|
72
|
+
previewContainer: document.querySelector("#markdown-preview"),
|
|
73
|
+
editorPane: document.querySelector("#editor-pane"),
|
|
74
|
+
previewPane: document.querySelector("#preview-pane"),
|
|
75
|
+
form: document.querySelector("form"),
|
|
76
|
+
loadMonaco: () => loadMonacoFromAmd(),
|
|
77
|
+
theme: "vs-dark",
|
|
78
|
+
uploadUrl: "/api/files/upload",
|
|
79
|
+
initialViewMode: "split",
|
|
80
|
+
viewModeStorageKey: "markdown-view-mode",
|
|
81
|
+
viewModeControls: [
|
|
82
|
+
{ element: document.querySelector("#edit-mode"), mode: "editor" },
|
|
83
|
+
{ element: document.querySelector("#split-mode"), mode: "split" },
|
|
84
|
+
{ element: document.querySelector("#preview-mode"), mode: "preview" }
|
|
85
|
+
],
|
|
86
|
+
hljs,
|
|
87
|
+
mermaid,
|
|
88
|
+
MathJax,
|
|
89
|
+
onSave: markdown => saveMarkdown(markdown),
|
|
90
|
+
onInitializationError: error => console.error("Monaco failed to initialize", error),
|
|
91
|
+
onPreviewError: error => console.error("Markdown preview failed", error)
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
await markdownEditor.setViewMode("preview");
|
|
95
|
+
markdownEditor.syncTextarea();
|
|
96
|
+
markdownEditor.setValue("# Updated");
|
|
97
|
+
markdownEditor.focus();
|
|
98
|
+
markdownEditor.dispose();
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The controller initializes Monaco for Markdown, keeps the original textarea synchronized,
|
|
102
|
+
debounces secure preview rendering, enhances highlight.js/Mermaid/MathJax, supports image
|
|
103
|
+
paste and drop, and applies consistent professional Monaco defaults (14px Cascadia Code
|
|
104
|
+
font stack, ligatures, semantic highlighting and comfortable vertical padding). Applications
|
|
105
|
+
can still override individual Monaco settings through `editorOptions`.
|
|
106
|
+
|
|
107
|
+
It also registers consistent Markdown shortcuts:
|
|
108
|
+
|
|
109
|
+
- <kbd>Ctrl/Cmd+B</kbd>: bold
|
|
110
|
+
- <kbd>Ctrl/Cmd+I</kbd>: italic
|
|
111
|
+
- <kbd>Ctrl/Cmd+K</kbd>: inline or fenced code
|
|
112
|
+
- <kbd>Ctrl/Cmd+L</kbd>: link
|
|
113
|
+
- <kbd>Ctrl/Cmd+1</kbd> through <kbd>Ctrl/Cmd+6</kbd>: headings
|
|
114
|
+
- <kbd>Ctrl/Cmd+S</kbd>: `onSave`
|
|
115
|
+
- <kbd>Enter</kbd>: continue bullet and ordered lists
|
|
116
|
+
|
|
117
|
+
If Monaco cannot be loaded, the original textarea becomes visible and continues to drive
|
|
118
|
+
the same preview. Applications therefore use one fallback policy instead of implementing
|
|
119
|
+
their own. Preview enhancement errors are reported through `onPreviewError` and never
|
|
120
|
+
replace a working Monaco editor. `onError` remains as a deprecated compatibility callback
|
|
121
|
+
for both error categories.
|
|
122
|
+
|
|
123
|
+
### Reading pages
|
|
124
|
+
|
|
125
|
+
```js
|
|
126
|
+
import {
|
|
127
|
+
initializeMarkdownReader,
|
|
128
|
+
printMarkdown
|
|
129
|
+
} from "@aiursoft/uistack-markdown-ui";
|
|
130
|
+
|
|
131
|
+
await initializeMarkdownReader({
|
|
132
|
+
container: ".markdown-body",
|
|
133
|
+
hljs,
|
|
134
|
+
mermaid,
|
|
135
|
+
MathJax
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
printButton.addEventListener("click", () =>
|
|
139
|
+
printMarkdown({ container: ".markdown-body", hljs, mermaid, MathJax }));
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Only code blocks inside the supplied container are highlighted. Mermaid is always
|
|
143
|
+
initialized in strict security mode. The reader also applies the shared responsive
|
|
144
|
+
Bootstrap table treatment and opens rendered links with `noopener noreferrer`.
|
|
145
|
+
|
|
146
|
+
### Image paste and drop
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
import { attachImageUpload } from "@aiursoft/uistack-markdown-ui";
|
|
150
|
+
|
|
151
|
+
const uploads = attachImageUpload({
|
|
152
|
+
editor,
|
|
153
|
+
eventTarget: editorContainer.parentElement,
|
|
154
|
+
uploadUrl: "/api/files/upload",
|
|
155
|
+
onError: (error, file) => console.error(`Failed to upload ${file.name}`, error)
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
// Call uploads.dispose() when the editor is destroyed.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The default queue uploads three files concurrently and retries HTTP 429 responses up
|
|
162
|
+
to five times. Clipboard images are accepted from both `clipboardData.files` and
|
|
163
|
+
`clipboardData.items`, and are captured before Monaco consumes the paste event. Use
|
|
164
|
+
the parent of Monaco's host container as `eventTarget`; `createMarkdownEditor()` does
|
|
165
|
+
this automatically. Use `getImageUrl` when an endpoint does not return
|
|
166
|
+
`internetPath` or `InternetPath`.
|
|
167
|
+
|
|
168
|
+
### Aiursoft application contract
|
|
169
|
+
|
|
170
|
+
MarkToHtml, MoongladeV2, EmployeeCenter and Kanban use the global IIFE build and the
|
|
171
|
+
same `createMarkdownEditor` contract. Monaco, live preview, highlight.js, Mermaid,
|
|
172
|
+
MathJax, Markdown shortcuts, image paste/drop, editor/split/preview modes and the
|
|
173
|
+
textarea fallback are required capabilities for these full editors.
|
|
174
|
+
|
|
175
|
+
DocsViewer and HowToCookViewer are reader-only consumers. Their Markdown containers
|
|
176
|
+
use `initializeMarkdownReader` for highlighting, Mermaid, MathJax, responsive tables
|
|
177
|
+
and safe external-link behavior.
|
|
178
|
+
|
|
179
|
+
Translate is an intentional product-level exception. It keeps its lightweight
|
|
180
|
+
CodeMirror Markdown input because translation does not need code highlighting,
|
|
181
|
+
Mermaid, MathJax, uploads or the full editing toolbar. It must not be treated as an
|
|
182
|
+
incomplete migration.
|
|
183
|
+
|
|
184
|
+
## Configuration
|
|
185
|
+
|
|
186
|
+
Configuration is passed as JavaScript options; the package has no configuration file or environment variables. The complete editor example above shows the application-owned DOM elements, Monaco loader, view controls, upload endpoint and callbacks.
|
|
187
|
+
|
|
188
|
+
**Rendering**
|
|
189
|
+
|
|
190
|
+
`renderMarkdown(markdown, options)` and `createMarkdownIt(options)` accept `breaks` (default `false`), `linkify` (`true`) and `typographer` (`true`). Native HTML is always disabled. Mermaid processing uses strict security mode. Math and diagram rendering require the corresponding application-supplied integrations; syntax highlighting is included in the renderer.
|
|
191
|
+
|
|
192
|
+
**Editor options and lifecycle**
|
|
193
|
+
|
|
194
|
+
`editorContainer`, `textarea` and `previewContainer` are required. Supply `monaco` or `loadMonaco` to create the editor; initialization failure reveals the textarea fallback. `theme` defaults to `vs`, `debounceMs` to `200`, and `initialViewMode` to `split`. `editorOptions` overrides Monaco editor settings. `form` defaults to the textarea's form; `editorPane` and `previewPane` default to their containers. `viewModeControls` defaults to an empty list; when `viewModeStorageKey` is supplied, a valid saved view mode overrides the initial mode. `markdownOptions`, `mermaidTheme`, `hljs`, `mermaid` and `MathJax` configure preview integration.
|
|
195
|
+
|
|
196
|
+
`onSave`, `onChange` and `onPreviewRendered` report edits and rendering. Use `onInitializationError` and `onPreviewError` for their separate failure categories; deprecated `onError` remains a compatibility callback. An optional `uploadUrl` enables image uploading, with `imageUploadOptions` for its settings. Call the returned controller's `dispose()` when the editor is removed.
|
|
197
|
+
|
|
198
|
+
**Reader options**
|
|
199
|
+
|
|
200
|
+
`initializeMarkdownReader` and `printMarkdown` take a required `container` selector, element or iterable, plus optional highlighter, Mermaid and MathJax dependencies (otherwise resolved from globals). `decorateTables` and `openLinksInNewTab` default to enabled. Tables use `table`, `table-striped` and `table-bordered` classes with a `table-responsive` wrapper; override `tableClassNames` or `tableWrapperClassName` when needed. Links opened in a new tab receive `noopener noreferrer`. `mermaidTheme` selects the diagram theme.
|
|
201
|
+
|
|
202
|
+
**Image upload options**
|
|
203
|
+
|
|
204
|
+
`editor` and `uploadUrl` are required for `attachImageUpload`. `eventTarget` defaults to the editor DOM node when available; without either target no DOM paste/drop listeners are attached. A Monaco host parent captures paste events before the editor. `fieldName` defaults to `file`, `concurrency` to `3` and `maxRetries` to `5`. Only HTTP 429 is retried, using `Retry-After` when present. Supply `fetch` to replace the fetch implementation, `getImageUrl` to customize response parsing (defaults to `internetPath` or `InternetPath`), and `onError` to report failures. Dispose the upload controller with the editor. The host provides and secures the upload endpoint.
|
|
205
|
+
|
|
23
206
|
## Development
|
|
24
207
|
|
|
25
|
-
Build with Node.js 22.18+ (22.x), 24.11+ (24.x), or 26+.
|
|
208
|
+
Build with Node.js 22.18+ (22.x), 24.11+ (24.x), or 26+. The current build is verified with Node.js 24.
|
|
209
|
+
|
|
210
|
+
From the repository root, install the locked dependencies, run the existing checks and create a package:
|
|
26
211
|
|
|
27
212
|
```bash
|
|
28
213
|
npm ci
|
|
29
214
|
npm run check
|
|
30
215
|
npm pack
|
|
31
216
|
```
|
|
217
|
+
|
|
218
|
+
The existing checks run TypeScript checking, Vitest coverage tests and the production build. `npm pack` creates a local archive; it does not publish a release.
|
|
219
|
+
|
|
220
|
+
## Documentation
|
|
221
|
+
|
|
222
|
+
See [usage and API](docs/usage.md) for editors, readers, image uploads and print integration. Exported option types and lifecycle contracts are in [src/index.ts](src/index.ts).
|
|
223
|
+
|
|
224
|
+
## How to contribute
|
|
225
|
+
|
|
226
|
+
There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
|
|
227
|
+
|
|
228
|
+
Even if you have push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.
|
|
229
|
+
|
|
230
|
+
We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
|
|
231
|
+
|
|
232
|
+
## License
|
|
233
|
+
|
|
234
|
+
Licensed under the [MIT License](LICENSE).
|