instui-markdown 0.0.7 → 0.0.8
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 +148 -11
- package/dist/index.mjs +5 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,23 +1,160 @@
|
|
|
1
|
-
#
|
|
1
|
+
# instui-markdown
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
React components for rendering markdown with [Instructure UI](https://instructure.design) components.
|
|
4
4
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
- Install dependencies:
|
|
5
|
+
## Installation
|
|
8
6
|
|
|
9
7
|
```bash
|
|
10
|
-
|
|
8
|
+
npm install instui-markdown rehype-instui-markdown
|
|
11
9
|
```
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
You also need the InstUI peer dependencies your app will use. At minimum:
|
|
14
12
|
|
|
15
13
|
```bash
|
|
16
|
-
|
|
14
|
+
npm install react react-markdown remark-gfm rehype-raw rehype-slug \
|
|
15
|
+
@instructure/ui-text @instructure/ui-heading @instructure/ui-link \
|
|
16
|
+
@instructure/ui-list @instructure/ui-view
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
## Usage
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
### `InstuiMarkdown`
|
|
22
|
+
|
|
23
|
+
Renders a markdown string using InstUI components.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { InstuiMarkdown } from "instui-markdown";
|
|
27
|
+
|
|
28
|
+
<InstuiMarkdown>{markdownString}</InstuiMarkdown>;
|
|
23
29
|
```
|
|
30
|
+
|
|
31
|
+
Pass `renderOptions` to control rendering behavior:
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
<InstuiMarkdown
|
|
35
|
+
renderOptions={{
|
|
36
|
+
link: { permalinks: true, externalIcon: true },
|
|
37
|
+
table: { sortable: true, hover: true },
|
|
38
|
+
code: { lineNumbers: true },
|
|
39
|
+
color: { enabled: true },
|
|
40
|
+
icons: { enabled: true },
|
|
41
|
+
}}
|
|
42
|
+
>
|
|
43
|
+
{markdownString}
|
|
44
|
+
</InstuiMarkdown>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### `InstuiMdxProvider`
|
|
48
|
+
|
|
49
|
+
Wraps MDX content and maps MDX elements to InstUI components.
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
import { InstuiMdxProvider } from "instui-markdown";
|
|
53
|
+
import Content from "./content.mdx";
|
|
54
|
+
|
|
55
|
+
<InstuiMdxProvider renderOptions={renderOptions}>
|
|
56
|
+
<Content />
|
|
57
|
+
</InstuiMdxProvider>;
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### `createInstuiMarkdownComponents`
|
|
61
|
+
|
|
62
|
+
Returns the component map directly if you need to pass it to `react-markdown` or an MDX provider yourself.
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
import ReactMarkdown from "react-markdown";
|
|
66
|
+
import { createInstuiMarkdownComponents } from "instui-markdown";
|
|
67
|
+
|
|
68
|
+
const components = createInstuiMarkdownComponents(renderOptions);
|
|
69
|
+
|
|
70
|
+
<ReactMarkdown components={components}>{markdown}</ReactMarkdown>;
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Render options
|
|
74
|
+
|
|
75
|
+
### `alert`
|
|
76
|
+
|
|
77
|
+
Controls alert-styled blockquotes. Uses [GFM alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts): `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`.
|
|
78
|
+
|
|
79
|
+
| Option | Type | Default | Description |
|
|
80
|
+
| ------------- | --------- | ------- | ------------------------------------ |
|
|
81
|
+
| `closeButton` | `boolean` | `false` | Shows a dismiss button on each alert |
|
|
82
|
+
|
|
83
|
+
### `table`
|
|
84
|
+
|
|
85
|
+
| Option | Type | Default | Description |
|
|
86
|
+
| ---------- | -------------------------------- | -------- | ------------------------------- |
|
|
87
|
+
| `display` | `"auto" \| "stacked" \| "fixed"` | `"auto"` | InstUI table layout mode |
|
|
88
|
+
| `hover` | `boolean` | `false` | Highlights rows on hover |
|
|
89
|
+
| `sortable` | `boolean` | `false` | Enables sortable column headers |
|
|
90
|
+
|
|
91
|
+
### `link`
|
|
92
|
+
|
|
93
|
+
| Option | Type | Default | Description |
|
|
94
|
+
| -------------------- | --------- | ---------------------- | ------------------------------------------ |
|
|
95
|
+
| `externalIcon` | `boolean` | `false` | Adds an icon to external links |
|
|
96
|
+
| `permalinks` | `boolean` | `false` | Appends a permalink anchor to each heading |
|
|
97
|
+
| `permalinkClassName` | `string` | `"mdx-heading-anchor"` | CSS class on permalink anchor elements |
|
|
98
|
+
|
|
99
|
+
### `code`
|
|
100
|
+
|
|
101
|
+
Fenced code blocks render using the InstUI `SourceCodeEditor`. Supported languages: `json`, `yaml`, `markdown`, `css`, `html`, `javascript` (and aliases `js`, `jsx`, `ts`, `tsx`, `yml`).
|
|
102
|
+
|
|
103
|
+
| Option | Type | Default | Description |
|
|
104
|
+
| --------------------- | ---------------- | ------- | -------------------------------------- |
|
|
105
|
+
| `editable` | `boolean` | `false` | Allows editing code blocks |
|
|
106
|
+
| `readOnly` | `boolean` | `true` | Marks code blocks as read-only |
|
|
107
|
+
| `lineNumbers` | `boolean` | `false` | Shows line numbers |
|
|
108
|
+
| `lineWrapping` | `boolean` | `false` | Wraps long lines |
|
|
109
|
+
| `spellCheck` | `boolean` | `false` | Enables spell check in editable blocks |
|
|
110
|
+
| `highlightActiveLine` | `boolean` | `false` | Highlights the cursor's line |
|
|
111
|
+
| `direction` | `"ltr" \| "rtl"` | `"ltr"` | Text direction |
|
|
112
|
+
|
|
113
|
+
### `color`
|
|
114
|
+
|
|
115
|
+
Wraps color literals in a visual swatch. Supports `#hex`, `rgb()`, `rgba()`, `hsl()`, and `hsla()` formats. Skips color values inside code fences.
|
|
116
|
+
|
|
117
|
+
| Option | Type | Default | Description |
|
|
118
|
+
| --------- | --------- | ------- | ----------------------------- |
|
|
119
|
+
| `enabled` | `boolean` | `false` | Renders color swatches inline |
|
|
120
|
+
|
|
121
|
+
### `icons`
|
|
122
|
+
|
|
123
|
+
Renders InstUI icons from `:iconName:` tokens. Supports Line, Solid, and Lucide icon variants. You can omit the `Icon` prefix and the `Line`/`Solid` suffix — `:Heart:`, `:HeartLine:`, and `:IconHeartLine:` all resolve to the same icon.
|
|
124
|
+
|
|
125
|
+
Add an optional hex color with a pipe: `:Heart|#F00:`.
|
|
126
|
+
|
|
127
|
+
Skips icon tokens inside code fences.
|
|
128
|
+
|
|
129
|
+
| Option | Type | Default | Description |
|
|
130
|
+
| --------- | --------- | ----------- | -------------------------------------------- |
|
|
131
|
+
| `enabled` | `boolean` | `false` | Renders `:icon:` tokens as InstUI icons |
|
|
132
|
+
| `color` | `string` | `undefined` | Default icon color (hex) for all icon tokens |
|
|
133
|
+
|
|
134
|
+
## Peer dependencies
|
|
135
|
+
|
|
136
|
+
`instui-markdown` requires the following peer dependencies. Install only what your content uses — the components map each markdown element to the matching InstUI package.
|
|
137
|
+
|
|
138
|
+
| Package | Used for |
|
|
139
|
+
| ------------------------------------ | ------------------------------------- |
|
|
140
|
+
| `react` | All components |
|
|
141
|
+
| `react-markdown` | Markdown parsing |
|
|
142
|
+
| `remark-gfm` | GFM tables, task lists, strikethrough |
|
|
143
|
+
| `rehype-raw` | Inline HTML in markdown |
|
|
144
|
+
| `rehype-slug` | Heading IDs |
|
|
145
|
+
| `rehype-autolink-headings` | Heading permalink anchors |
|
|
146
|
+
| `@mdx-js/react` | `InstuiMdxProvider` |
|
|
147
|
+
| `@instructure/ui-alerts` | `> [!NOTE]` and other alerts |
|
|
148
|
+
| `@instructure/ui-badge` | Color swatch badges |
|
|
149
|
+
| `@instructure/ui-checkbox` | Task list items |
|
|
150
|
+
| `@instructure/ui-color-utils` | Color contrast for swatches |
|
|
151
|
+
| `@instructure/ui-heading` | `h1`–`h6` |
|
|
152
|
+
| `@instructure/ui-icons` | Icon tokens and permalink icons |
|
|
153
|
+
| `@instructure/ui-img` | Images |
|
|
154
|
+
| `@instructure/ui-link` | Links |
|
|
155
|
+
| `@instructure/ui-list` | Ordered and unordered lists |
|
|
156
|
+
| `@instructure/ui-source-code-editor` | Fenced code blocks |
|
|
157
|
+
| `@instructure/ui-svg-images` | Inline SVG elements |
|
|
158
|
+
| `@instructure/ui-table` | Tables |
|
|
159
|
+
| `@instructure/ui-text` | Paragraphs and inline text |
|
|
160
|
+
| `@instructure/ui-view` | Block wrappers and horizontal rules |
|
package/dist/index.mjs
CHANGED
|
@@ -463,16 +463,19 @@ function createSpanComponent(options) {
|
|
|
463
463
|
if (IconComponent) {
|
|
464
464
|
const resolvedColor = inlineIconColor ?? options.iconColor;
|
|
465
465
|
const normalizedIconColor = resolvedColor && isLiteralColorValue(resolvedColor) ? normalizeColorForSwatch(resolvedColor) : void 0;
|
|
466
|
+
const sizeProps = IconComponent.displayName?.startsWith("InstUIIcon_") ? { size: "x-small" } : {};
|
|
466
467
|
if (normalizedIconColor) return /* @__PURE__ */ jsx("span", {
|
|
467
468
|
style: { color: normalizedIconColor },
|
|
468
469
|
children: /* @__PURE__ */ jsx(IconComponent, {
|
|
469
470
|
title: iconName,
|
|
470
|
-
color: "inherit"
|
|
471
|
+
color: "inherit",
|
|
472
|
+
...sizeProps
|
|
471
473
|
})
|
|
472
474
|
});
|
|
473
475
|
return /* @__PURE__ */ jsx(IconComponent, {
|
|
474
476
|
title: iconName,
|
|
475
|
-
color: (resolvedColor === "currentColor" ? "inherit" : resolvedColor) ?? "inherit"
|
|
477
|
+
color: (resolvedColor === "currentColor" ? "inherit" : resolvedColor) ?? "inherit",
|
|
478
|
+
...sizeProps
|
|
476
479
|
});
|
|
477
480
|
}
|
|
478
481
|
}
|