From a4b750bd65e0c4bcf5a100dccac4e0abcebc2a5c Mon Sep 17 00:00:00 2001 From: jaywcjlove <398188662@qq.com> Date: Sat, 23 Dec 2023 15:12:52 +0800 Subject: [PATCH] doc: Update react-markdown v9 document. --- core/README.md | 145 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 109 insertions(+), 36 deletions(-) diff --git a/core/README.md b/core/README.md index c0d1c274..4bf69e58 100644 --- a/core/README.md +++ b/core/README.md @@ -418,7 +418,7 @@ export default function Demo() { } ``` -### Options Props +## Options Props ```typescript import { ReactMarkdownProps } from 'react-markdown'; @@ -445,7 +445,7 @@ type MarkdownPreviewProps = { - `className` (`string?`)\ Wrap the markdown in a `div` with this class name -This [`ReactMarkdownProps`](https://github.com/remarkjs/react-markdown/tree/02bac837bf141cdb8face360fb88be6fa33ab194#props) details. [Upgrade `react-markdown` v6](https://github.com/remarkjs/react-markdown/blob/15b4757082cf3f32a25eba0b8ea30baf751a8b40/changelog.md#600---2021-04-15) +This [`ReactMarkdownProps`](https://github.com/remarkjs/react-markdown/tree/02bac837bf141cdb8face360fb88be6fa33ab194#props) details. [Upgrade `react-markdown` v9](https://github.com/remarkjs/react-markdown/tree/a27d335fc5419db4a2811e7f589d6467218346de?tab=readme-ov-file#options) - `children` (`string`, default: `''`)\ Markdown to parse @@ -453,43 +453,9 @@ This [`ReactMarkdownProps`](https://github.com/remarkjs/react-markdown/tree/02ba Wrap the markdown in a `div` with this class name - `skipHtml` (`boolean`, default: ~~`false`~~ -> [`true`](https://github.com/uiwjs/react-markdown-preview/issues/205) )\ Ignore HTML in Markdown completely -- `sourcePos` (`boolean`, default: `false`)\ - Pass a prop to all components with a serialized position - (`data-sourcepos="3:1-3:13"`) -- `rawSourcePos` (`boolean`, default: `false`)\ - Pass a prop to all components with their [position][] - (`sourcePosition: {start: {line: 3, column: 1}, end:…}`) -- `includeElementIndex` (`boolean`, default: `false`)\ - Pass the `index` (number of elements before it) and `siblingCount` (number - of elements in parent) as props to all components -- `allowedElements` (`Array.`, default: `undefined`)\ - Tag names to allow (can’t combine w/ `disallowedElements`). - By default all elements are allowed -- `disallowedElements` (`Array.`, default: `undefined`)\ - Tag names to disallow (can’t combine w/ `allowedElements`). - By default no elements are disallowed - `allowElement` (`(element, index, parent) => boolean?`, optional)\ Function called to check if an element is allowed (when truthy) or not. `allowedElements` / `disallowedElements` is used first! -- `unwrapDisallowed` (`boolean`, default: `false`)\ - Extract (unwrap) the children of not allowed elements. - By default, when `strong` is not allowed, it and it’s children is dropped, - but with `unwrapDisallowed` the element itself is dropped but the children - used -- `linkTarget` (`string` or `(href, children, title) => string`, optional)\ - Target to use on links (such as `_blank` for ` string`, default: - [`./uri-transformer.js`](https://github.com/remarkjs/react-markdown/blob/02bac837bf141cdb8face360fb88be6fa33ab194/lib/uri-transformer.js), optional)\ - URL to use for links. - The default allows only `http`, `https`, `mailto`, and `tel`, and is - exported from this module as `uriTransformer`. - Pass `null` to allow all URLs. - See [security][] -- `transformImageUri` (`(src, alt, title) => string`, default: - [`./uri-transformer.js`](https://github.com/remarkjs/react-markdown/blob/02bac837bf141cdb8face360fb88be6fa33ab194/lib/uri-transformer.js), optional)\ - Same as `transformLinkUri` but for images -- `components` (`Object.`, default: `{}`)\ - Object mapping tag names to React components - `remarkPlugins` (`Array.`, default: `[]`)\ List of [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) to use. See the next section for examples on how to pass options @@ -497,6 +463,113 @@ This [`ReactMarkdownProps`](https://github.com/remarkjs/react-markdown/tree/02ba List of [rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins) to use. See the next section for examples on how to pass options +> [!NOTE] +> +> [Upgrade `react-markdown` ~~v8~~ to v9](https://github.com/remarkjs/react-markdown/blob/a27d335fc5419db4a2811e7f589d6467218346de/changelog.md?plain=1#L5-L144) + +### Add `urlTransform` + +The `transformImageUri` and `transformLinkUri` were removed. +Having two functions is a bit much, particularly because there are more URLs +you might want to change (or which might be unsafe so *we* make them safe). +And their name and APIs were a bit weird. +You can use the new `urlTransform` prop instead to change all your URLs. + +### Remove `linkTarget` + +The `linkTarget` option was removed; you should likely not set targets. +If you want to, use +[`rehype-external-links`](https://github.com/rehypejs/rehype-external-links). + +### Remove `includeElementIndex` + +The `includeElementIndex` option was removed, so `index` is never passed to +components. +Write a plugin to pass `index`: + +
+Show example of plugin + +```jsx +import {visit} from 'unist-util-visit' + +function rehypePluginAddingIndex() { + /** + * @param {import('hast').Root} tree + * @returns {undefined} + */ + return function (tree) { + visit(tree, function (node, index) { + if (node.type === 'element' && typeof index === 'number') { + node.properties.index = index + } + }) + } +} +``` + +
+ +### Remove `rawSourcePos` + +The `rawSourcePos` option was removed, so `sourcePos` is never passed to +components. +All components are passed `node`, so you can get `node.position` from them. + +### Remove `sourcePos` + +The `sourcePos` option was removed, so `data-sourcepos` is never passed to +elements. +Write a plugin to pass `index`: + +
+Show example of plugin + +```jsx +import {stringifyPosition} from 'unist-util-stringify-position' +import {visit} from 'unist-util-visit' + +function rehypePluginAddingIndex() { + /** + * @param {import('hast').Root} tree + * @returns {undefined} + */ + return function (tree) { + visit(tree, function (node) { + if (node.type === 'element') { + node.properties.dataSourcepos = stringifyPosition(node.position) + } + }) + } +} +``` + +
+ +### Remove extra props passed to certain components + +When overwriting components, these props are no longer passed: + +* `inline` on `code` + — create a plugin or use `pre` for the block +* `level` on `h1`, `h2`, `h3`, `h4`, `h5`, `h6` + — check `node.tagName` instead +* `checked` on `li` + — check `task-list-item` class or check `props.children` +* `index` on `li` + — create a plugin +* `ordered` on `li` + — create a plugin or check the parent +* `depth` on `ol`, `ul` + — create a plugin +* `ordered` on `ol`, `ul` + — check `node.tagName` instead +* `isHeader` on `td`, `th` + — check `node.tagName` instead +* `isHeader` on `tr` + — create a plugin or check children + + ## Markdown Features ### Supports for CSS Style