feat: deprecate soft break transform behavior after 2.2.0 (#1686)

* feat: only enabled soft break before 2.2.0

* feat: use custom remark-breaks replace remark-breaks

* fix: fix null safe issue

* refactor: not reassigning processor

* feat: keep soft break exclude dumi

* feat: add deprecation warning with soft break

* feat: only output warnings once per run

* refactor: optimize import

* feat: change warning function and add color

* feat: ignore text nodes with only one break symbol

Author: suiyun39

package.json

@@ -106,6 +106,7 @@
     "html2sketch": "^1.0.1",
     "js-yaml": "^4.1.0",
     "lodash.throttle": "^4.1.1",
+    "mdast-util-find-and-replace": "^2.2.2",
     "mdast-util-to-string": "^3.1.0",
     "nprogress": "^0.2.0",
     "pluralize": "^8.0.0",
@@ -122,7 +123,6 @@
     "rehype-autolink-headings": "^6.1.1",
     "rehype-remove-comments": "^5.0.0",
     "rehype-stringify": "^9.0.3",
-    "remark-breaks": "^3.0.2",
     "remark-directive": "^2.0.1",
     "remark-frontmatter": "^4.0.1",
     "remark-gfm": "^3.0.1",

pnpm-lock.yaml

@@ -25,3 +25,5 @@ export const PICKED_PKG_FIELDS = {
 export const USELESS_TMP_FILES = ['tsconfig.json', 'typings.d.ts'];
 
 export const VERSION_2_LEVEL_NAV = '^2.2.0';
+
+export const VERSION_2_DEPRECATE_SOFT_BREAKS = '^2.2.0';

src/constants.ts

@@ -43,6 +43,7 @@ export default (api: IApi) => {
       extraRemarkPlugins: api.config.extraRemarkPlugins,
       extraRehypePlugins: api.config.extraRehypePlugins,
       routes: api.appData.routes,
+      pkg: api.pkg,
     };
 
     memo.module

src/features/compile/index.ts

@@ -1,8 +1,10 @@
 import type { IParsedBlockAsset } from '@/assetParsers/block';
 import type { IRouteMeta } from '@/client/theme-api/types';
-import type { IDumiConfig, IDumiTechStack } from '@/types';
+import { VERSION_2_DEPRECATE_SOFT_BREAKS } from '@/constants';
+import type { IApi, IDumiConfig, IDumiTechStack } from '@/types';
 import enhancedResolve from 'enhanced-resolve';
 import type { IRoute } from 'umi';
+import { semver } from 'umi/plugin-utils';
 import type { Plugin, Processor } from 'unified';
 import type { Data } from 'vfile';
 import rehypeDemo from './rehypeDemo';
@@ -17,6 +19,7 @@ import rehypeRaw from './rehypeRaw';
 import rehypeSlug from './rehypeSlug';
 import rehypeStrip from './rehypeStrip';
 import rehypeText from './rehypeText';
+import remarkBreaks from './remarkBreaks';
 import remarkContainer from './remarkContainer';
 import remarkEmbed from './remarkEmbed';
 import remarkMeta from './remarkMeta';
@@ -63,13 +66,25 @@ export interface IMdTransformerOptions {
   extraRemarkPlugins?: IDumiConfig['extraRemarkPlugins'];
   extraRehypePlugins?: IDumiConfig['extraRehypePlugins'];
   routes: Record<string, IRoute>;
+  pkg: IApi['pkg'];
 }
 
 export interface IMdTransformerResult {
   content: string;
   meta: Data;
 }
 
+/**
+ * keep markdown soft break before 2.2.0
+ */
+function keepSoftBreak(pkg: IApi['pkg']) {
+  // for dumi local example project
+  if (pkg?.name?.startsWith('@examples/') || pkg?.name === 'dumi') return false;
+
+  const ver = pkg?.devDependencies?.dumi ?? pkg?.dependencies?.dumi ?? '^2.0.0';
+  return !semver.subset(ver, VERSION_2_DEPRECATE_SOFT_BREAKS);
+}
+
 function applyUnifiedPlugin(opts: {
   processor: Processor;
   plugin: NonNullable<IMdTransformerOptions['extraRemarkPlugins']>[0];
@@ -92,7 +107,6 @@ export default async (raw: string, opts: IMdTransformerOptions) => {
   const { default: remarkParse } = await import('remark-parse');
   const { default: remarkFrontmatter } = await import('remark-frontmatter');
   const { default: remarkDirective } = await import('remark-directive');
-  const { default: remarkBreaks } = await import('remark-breaks');
   const { default: remarkGfm } = await import('remark-gfm');
   const { default: remarkRehype } = await import('remark-rehype');
   const { default: rehypeAutolinkHeadings } = await import(
@@ -117,9 +131,12 @@ export default async (raw: string, opts: IMdTransformerOptions) => {
     })
     .use(remarkDirective)
     .use(remarkContainer)
-    .use(remarkBreaks)
     .use(remarkGfm);
 
+  if (keepSoftBreak(opts.pkg)) {
+    processor.use(remarkBreaks, { fileAbsPath: opts.fileAbsPath });
+  }
+
   // apply extra remark plugins
   opts.extraRemarkPlugins?.forEach((plugin) =>
     applyUnifiedPlugin({

src/loaders/markdown/transformer/index.ts

@@ -0,0 +1,47 @@
+import type { IMdTransformerOptions } from '@/loaders/markdown/transformer/index';
+import type { Root } from 'mdast';
+import type { ReplaceFunction } from 'mdast-util-find-and-replace';
+import { chalk, logger } from 'umi/plugin-utils';
+
+let findAndReplace: typeof import('mdast-util-find-and-replace').findAndReplace;
+
+(async () => {
+  ({ findAndReplace } = await import('mdast-util-find-and-replace'));
+})();
+
+const warningLock = new Map<string, true>();
+
+function logDeprecationWarning(fileAbsPath: string) {
+  if (warningLock.get(fileAbsPath)) return;
+
+  warningLock.set(fileAbsPath, true);
+
+  logger.warn(
+    'Detected that you are using soft breaks, dumi will transform them into spaces after the declaration',
+    'version greater than or equal to `2.2.0`, however, they are still being transformed as line breaks now, please',
+    'migrate them to hard breaks before upgrading the declaration version for dumi.\n',
+    chalk.grey(`  at ${fileAbsPath}\n`),
+    chalk.grey('  see also: https://github.com/umijs/dumi/issues/1683\n'),
+  );
+}
+
+export default function remarkBreaks(
+  opts: Pick<IMdTransformerOptions, 'fileAbsPath'>,
+) {
+  const replace: ReplaceFunction = (_, match) => {
+    if (
+      match.input === '\n' ||
+      match.input === '\r' ||
+      match.input === '\r\n'
+    ) {
+      return false;
+    }
+
+    logDeprecationWarning(opts.fileAbsPath);
+    return { type: 'break' };
+  };
+
+  return (tree: Root) => {
+    findAndReplace(tree, /\r?\n|\r/g, replace);
+  };
+}