remark-cjk-friendly

v2.3.1

Published

10 days ago

remark plugin to make Markdown emphasis (`**`) in CommonMark (and MDX) more friendly with Chinese, Japanese, and Korean (CJK)

0High
0Medium
0Low

tats-u

remark-plugin remark markdown japanese chinese korean cjk mdast unified

remark-cjk-friendly

Node Current [Snyk Security]

A remark plugin to make Markdown emphasis (**) in CommonMark (and MDX) compatible with Chinese, Japanese, and Korean (CJK).

CommonMark（・MDX）の強調記号(**)を日本語・中国語・韓国語にきちんと対応させるためのremarkプラグイン

一个 remark 插件，用于使 CommonMark（和 MDX）的强调标记(**)能够正确支持中文、日语和韩语文本。

CommonMark(및 MDX)의 강조 표시(**)를 한국어, 일본어, 중국어와 호환되도록 만드는 remark 플러그인.

[!NOTE] This package does not support the strikethrough syntax (~~) in GFM (GitHub Flavored Markdown). If you want to support it, please use remark-cjk-friendly-gfm-strikethrough along with this package.
本パッケージはGitHub Flavored Markdown（GFM）の取り消し線（~~）に対応しません。対応させたい場合は、remark-cjk-friendly-gfm-strikethroughを併用してください。
本包不支持 GitHub Flavored Markdown（GFM）的删除线（~~）。如果需要支持，请同时使用 remark-cjk-friendly-gfm-strikethrough。
이 패키지는 GitHub Flavored Markdown(GFM)의 취소선(~~)을 지원하지 않습니다. 지원하고 싶은 경우에는 remark-cjk-friendly-gfm-strikethrough를 함께 사용해 주세요.

Problem / 問題 / 问题 / 문제

CommonMark has a problem that the following emphasis marks ** are not recognized as emphasis marks in Japanese, Chinese, and Korean.

CommonMarkには、日本語・中国語・韓国語内の次のような強調記号(**)が強調記号として認識されない問題があります。

CommonMark存在以下问题：在中文、日语和韩语文本中，强调标记**不会被识别为强调标记。

CommonMark는 한국어, 일본어, 중국어에서 다음과 같은 강조 표시 **가 강조 표시로 인식되지 않는 문제가 있습니다.

**このアスタリスクは強調記号として認識されず、そのまま表示されます。**この文のせいで。

**该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。

**이 별표는 강조 표시로 인식되지 않고 그대로 표시됩니다(이 괄호 때문에)**이 문장 때문에.

This problem occurs because the character just inside the ** is a (Japanese or Chinese) punctuation mark (。) or parenthesis and the character just outside is not a space or punctuation mark.

これが起こった原因は、終了側の**のすぐ内側が約物（。やカッコ）、かつ外側が約物や空白以外の文字であるためです。

这个问题是因为在**的结束部分，内侧字符是标点符号（。）或括号，而外侧字符不是空格或标点符号。

이 문제는 ** 바로 안쪽의 문자가 (일본어나 중국어) 문장 부호(。) 또는 괄호이고 바깥쪽 문자가 공백이나 문장 부호가 아니기 때문에 발생합니다.

Of course, not only the end side but also the start side has the same issue.

もちろん終了側だけでなく、開始側も同様の問題が存在します。

当然，不仅是结束侧，开始侧也存在同样的问题。

물론 끝나는 부분뿐만 아니라 시작하는 부분에서도 동일한 문제가 있습니다.

CommonMark issue: https://github.com/commonmark/commonmark-spec/issues/650

Demo / デモ / 演示 / 데모

https://tats-u.github.io/markdown-cjk-friendly

When should I use this? / このパッケージを使うべき場合 / 何时使用此包 / 이 패키지를 사용해야 하는 경우

If you are an engineer who must handle Chinese, Japanese, and Korean content that cannot be fully supervised, it is strongly recommended to use this package (adopt this specification instead of plain CommonMark or GFM). "Cannot be fully supervised" refers to situations such as:

When you need to display user-generated or AI-generated content as-is
When many translators do not understand this CommonMark behavior, and you cannot provide real-time rendering previews similar to production, and <strong> tags are not allowed
- When using translation services like Crowdin or Transifex
- When the person responsible for translation quality is not an engineer or does not understand this CommonMark behavior

Additionally, if you are creating Markdown-related software or services primarily targeting Chinese, Japanese, or Korean users (or all of them), it is strongly recommended to use this package (adopt this specification).

もしエンジニアであるあなたが全てに監修を入れられない日本語・中国語・韓国語のコンテンツを扱わなければならない場合、このパッケージを使う（素のCommonMarkやGFMではなく、この仕様を採用する）ことを強く推奨します。「全てに監修を入れられない」というのは、例えば次のようなものを指します。

ユーザまたはAIが作成したコンテンツをそのまま表示する必要がある場合
翻訳者に、このCommonMarkの仕様を理解していない人も多く、なおかつリアルタイムで本番同様の描画プレビューを提供できず、<strong>タグを許可していない場合
- 翻訳にCrowdin・Transifexなどの翻訳サービスを使っている場合
- 翻訳の品質に責任を負っている人が非エンジニアである、またはCommonMarkのこの挙動を理解していない場合

また、あなたが主に日本人・中国人・韓国人のいずれかまたは全てを対象としたMarkdown関連のソフトウェアやサービスを作成する場合も、このパッケージを使う（この仕様を採用する）ことを強く推奨します。

如果作为工程师的您必须处理无法全面监督的中文、日文和韩文内容，强烈建议使用这个包装（采用此规范，而不是普通的CommonMark或GFM）。"无法全面监督"指的是以下情况：

当需要按原样显示用户生成或AI生成的内容时
当许多翻译人员不理解这个CommonMark行为，而且无法提供类似生产环境的实时渲染预览，并且不允许使用<strong>标签时
- 当使用Crowdin或Transifex等翻译服务时
- 当负责翻译质量的人不是工程师或不理解这个CommonMark行为时

此外，如果您正在创建主要面向中国人、日本人或韩国人（或全部）的Markdown相关软件或服务，也强烈建议采用此规范。

엔지니어로서 완전히 감독할 수 없는 일본어, 중국어, 한국어 콘텐츠를 다뤄야 하는 경우 이 패키지를 사용(일반 CommonMark나 GFM 대신 이 사양을 채택)할 것을 강력히 권장합니다. '완전히 감독할 수 없는'이란 다음과 같은 상황을 의미합니다.

사용자 또는 AI가 생성한 콘텐츠를 그대로 표시해야 하는 경우
많은 번역자가 CommonMark의 동작을 이해하지 못하고, 실시간으로 실제 환경과 유사한 렌더링 미리보기를 제공할 수 없으며, <strong> 태그가 허용되지 않는 경우
- Crowdin이나 Transifex 같은 번역 서비스를 사용하는 경우
- 번역 품질에 책임을 지는 사람이 엔지니어가 아니거나 CommonMark의 동작을 이해하지 못하는 경우

또한, 주로 한국어, 일본어, 중국어 사용자(또는 모두)를 대상으로 하는 Markdown 관련 소프트웨어나 서비스를 만들고 있다면 이 패키지를 사용(이 사양을 채택)할 것을 강력히 권장합니다.

Example of 1. (Chinese) / 1.の例（中国語） / 1.的例子 / 1.의 예시(중국어):

❌️Plain CommonMark / 素のCommonMark / 原生CommonMark / 기본 CommonMark:

plain CommonMark

✅️With this spec / 本規格 / 这个规范 / 이 사양:

with this spec

Image source: CherryHQ/cherry-studio#4119

Runtime Requirements / 実行環境の要件 / 运行环境要求 / 런타임 요구 사항

This package is ESM-only. It requires Node.js 18 or later. (I have only tested it on 20 and later. There is no factor that would prevent it from working on 18, but I do not guarantee its operation on 18.)

本パッケージはESM専用です。Node.js 18以上が必要です。（動作検証は20以降でのみ行っています。18での動作を妨げる要因はありませんが、動作の保証はありません）

此包仅支持ESM。需要Node.js 18或更高版本。（我只测试了20及以后的版本。没有因素会阻止它在18上工作，但我不保证在18上的操作。）

본 패키지는 ESM 전용입니다. Node.js 18 이상이 필요합니다. (동작 검증은 20 이후 버전에서만 수행했습니다. 18에서 동작을 방해하는 요인은 없으나, 동작을 보장하지는 않습니다)

Installation / インストール / 安装 / 설치

Install remark-cjk-friendly via npm:

remark-cjk-friendlyをnpmでインストールしてください。

通过 npm 安装 remark-cjk-friendly。

remark-cjk-friendly를 npm으로 설치하세요.

npm install remark-cjk-friendly

If you use another package manager, please replace npm install with the command of the package manager you use (e.g. pnpm add or yarn add).

npm以外のパッケージマネージャを使う場合は、npm installを当該パッケージマネージャのコマンド（例：pnpm add・yarn add）に置き換えてください。

如果使用其他包管理器，请将 npm install 替换为当时包管理器的命令（例如：pnpm add、yarn add）。

npm이 아닌 다른 패키지 매니저를 사용하는 경우 npm install을 해당 패키지 매니저의 명령어(예: pnpm add, yarn add)로 바꿔 주세요.

Usage / 使い方 / 用法 / 사용법

Import remark-cjk-friendly with other remark-related packages, and use the plugin as follows:

remark-cjk-friendlyを他のremark関連パッケージと一緒にインポートし、次のようにプラグインを使用してください。

将 remark-cjk-friendly 与其他 remark 相关的包一起导入，然后使用插件如下:

remark-cjk-friendly를 다른 remark 관련 패키지와 함께 가져온 후 다음과 같이 플러그인을 사용하세요.

import rehypeStringify from "rehype-stringify";
import remarkCjkFriendly from "remark-cjk-friendly";
import remarkGfm from "remark-gfm";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";

// e.g. in the case that you want to enable GFM and obtain HTML output
const processor = unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkCjkFriendly)
  .use(remarkRehype)
  .use(rehypeStringify);

const htmlResult = (await processor.process(markdownString)).toString();

This plugin also wires the reverse path for remark-stringify / mdast-util-to-markdown, so CJK text around * / ** stays raw when it is valid under this specification instead of being escaped as character references. Since this serialization feature may be removed from the default entry point of remark-cjk-friendly in a future version, it is strongly recommended to import from remark-cjk-friendly/bidi. For users who only need parsing or serialization and want to minimize bundle size (reduces a few KB), import from remark-cjk-friendly/parseOnly or remark-cjk-friendly/serializeOnly respectively.

| Entry point | Parsing (Markdown → AST) | Serialization (AST → Markdown) | | --- | --- | --- | | remark-cjk-friendly | ✅ | ⚠️ | | remark-cjk-friendly/bidi | ✅ | ✅ | | remark-cjk-friendly/parseOnly | ✅ | ❌ | | remark-cjk-friendly/serializeOnly | ❌ | ✅ |

このプラグインはremark-stringify / mdast-util-to-markdown向けの逆方向シリアライズ拡張にも対応しており、この仕様で妥当なケースでは* / **の前後にあるCJK文字が文字参照へエスケープされず、そのまま出力されます。このシリアライズ機能は将来のバージョンでremark-cjk-friendlyのデフォルトのエントリポイントから削除するかもしれませんので、remark-cjk-friendly/bidiからインポートすることを強く推奨します。また、パース・シリアライズの片方しか使わない場合でバンドルサイズを最小限に抑えたい場合（数KB削減）は、remark-cjk-friendly/parseOnlyまたはremark-cjk-friendly/serializeOnlyからインポートしてください。

| エントリポイント | パース（Markdown → AST） | シリアライズ（AST → Markdown） | | --- | --- | --- | | remark-cjk-friendly | ⭕️ | ⚠️ | | remark-cjk-friendly/bidi | ⭕️ | ⭕️ | | remark-cjk-friendly/parseOnly | ⭕️ | ❌ | | remark-cjk-friendly/serializeOnly | ❌ | ⭕️ |

此插件还会自动接入 remark-stringify / mdast-util-to-markdown 的反向序列化扩展，因此在本规范允许的情况下，* / ** 周围的 CJK 文字会保持原样输出，而不会被转义为字符引用。由于此序列化功能可能在未来版本中从 remark-cjk-friendly 的默认入口点中删除，强烈建议从 remark-cjk-friendly/bidi 导入。如果只需要解析或序列化其中之一，并希望尽量减小打包体积（可减少数KB），请分别从 remark-cjk-friendly/parseOnly 或 remark-cjk-friendly/serializeOnly 导入。

| 入口点 | 解析（Markdown → AST） | 序列化（AST → Markdown） | | --- | --- | --- | | remark-cjk-friendly | ✅ | ⚠️ | | remark-cjk-friendly/bidi | ✅ | ✅ | | remark-cjk-friendly/parseOnly | ✅ | ❌ | | remark-cjk-friendly/serializeOnly | ❌ | ✅ |

이 플러그인은 remark-stringify / mdast-util-to-markdown용 역방향 직렬화 확장도 자동으로 연결하므로, 이 사양에서 유효한 경우 * / ** 주변의 CJK 문자가 문자 참조로 이스케이프되지 않고 그대로 출력됩니다. 이 직렬화 기능은 향후 버전에서 remark-cjk-friendly의 기본 엔트리 포인트에서 제거될 수 있으므로, remark-cjk-friendly/bidi에서 가져오는 것을 강력히 권장합니다. 파싱과 직렬화 중 하나만 필요하고 번들 크기를 최소화하려는 경우（수 KB 절감）에는 각각 remark-cjk-friendly/parseOnly 또는 remark-cjk-friendly/serializeOnly에서 가져오세요.

| 엔트리 포인트 | 파싱（Markdown → AST） | 직렬화（AST → Markdown） | | --- | --- | --- | | remark-cjk-friendly | ⭕️ | ⚠️ | | remark-cjk-friendly/bidi | ⭕️ | ⭕️ | | remark-cjk-friendly/parseOnly | ⭕️ | ❌ | | remark-cjk-friendly/serializeOnly | ❌ | ⭕️ |

For MDX, add remarkCjkFriendly to the remarkPlugins array in the config object:

MDXでは、設定オブジェクトのremarkPlugins配列にremarkCjkFriendlyを追加してください。

对于 MDX，将 remarkCjkFriendly 添加到配置对象的 remarkPlugins 数组中。

MDX의 경우 설정 객체의 remarkPlugins 배열에 remarkCjkFriendly를 추가해 주세요.

const someMdxConfig = {
  remarkPlugins: [remarkGfm, remarkCjkFriendly, ...otherRemarkPlugins],
  rehypePlugins: [...someRehypePlugins],
};

This plugin is not compatible with Rust-based remark-compatible Markdown/MDX parsers, including the following:

When using this plugin, you need to use the real remark parser that internally uses micromark, which is implemented in pure JavaScript and thus monkey-patchable, instead of these parsers. Here are well-known use cases. If applicable, please take the corresponding workaround.

| Well-known use case | Workaround | | --- | --- | | mdxRs option in Rspress 1.x | Set it to false | | mdxRs option in Next.js (@next/mdx) | Set it to false | | Astro 6.4 or later | Use @astrojs/markdown-remark instead of @astrojs/markdown-satteri |

本プラグインは、次を含むRustベースのremark互換のMarkdown・MDXパーサと互換性がありません。

mdx-rsクレート
@rspress/mdx-rsパッケージ
Sätteri

本プラグインを使う場合、これらのパーサではなく、純JavaScriptで実装されているためモンキーパッチ可能なパーサmicromarkを中で使用している、本物のremarkパーサを使う必要があります。次のような利用先が有名です。当てはまる場合は、対応する回避策を取ってください。

| 有名な利用先 | 回避策 | | --- | --- | | Rspress 1.xのmdxRsオプション | falseにしてください | | Next.js（@next/mdx）のmdxRsオプション | falseにしてください | | Astro 6.4以降 | @astrojs/markdown-satteriではなく、@astrojs/markdown-remarkを使ってください |

本插件与以下Rust语言实现的remark兼容的Markdown/MDX解析器不兼容：

使用本插件时，需要使用内部使用micromark（由纯JavaScript实现，因此可以进行猴子补丁）的真正的remark解析器，而不是这些解析器。以下是常见的使用场景，如果适用，请采取相应的解决方法。

| 常见使用场景 | 解决方法 | | --- | --- | | Rspress 1.x的mdxRs选项 | 请设置为false | | Next.js（@next/mdx）的mdxRs选项 | 请设置为false | | Astro 6.4及以后版本 | 请使用@astrojs/markdown-remark而不是@astrojs/markdown-satteri |

이 플러그인은 다음을 포함하는 Rust 기반의 remark 호환 Markdown/MDX 파서와 호환되지 않습니다.

mdx-rs 크레이트
@rspress/mdx-rs 패키지
Sätteri

이 플러그인을 사용할 때는 이러한 파서 대신, 순수 JavaScript로 구현되어 있어 몽키 패치가 가능한 micromark를 내부적으로 사용하는 진정한 remark 파서를 사용해야 합니다. 다음과 같은 잘 알려진 사용처가 있습니다. 해당하는 경우에는 그에 맞는 해결 방법을 적용하세요.

| 잘 알려진 사용처 | 해결 방법 | | --- | --- | | Rspress 1.x의 mdxRs 옵션 | false로 설정하세요 | | Next.js（@next/mdx）의 mdxRs 옵션 | false로 설정하세요 | | Astro 6.4 이후 | @astrojs/markdown-satteri 대신 @astrojs/markdown-remark를 사용하세요 |

Compatibility with the other languages / 他言語との互換性 / 与其他语言的兼容性 / 다른 언어와의 호환성

This modification of the specification does not affect the other languages than Chinese, Japanese, and Korean. Even if your application or document has translations or content in other languages, it will not be affected, so please feel free to use this packages. I assure that even with this package (amendment suggestion), remark still outputs the same HTML for all CommonMark test cases as of 0.31.2.

この仕様変更提案は、日本語・中国語・韓国語以外の言語には影響しません。アプリケーションやドキュメントに他言語の翻訳やコンテンツが含まれていても影響はありませんので、安心して本パッケージをご利用ください。本パッケージ（修正案）を使用しても、0.31.2時点の全てのCommonMarkテストケースで、remarkが同じHTMLを出力することを保証しています。

除中文、日文和韩文外，建议的规范变更不会影响其他语言。请放心使用此软件包，因为如果您的应用程序或文档包含其他语言的翻译或内容，也不会受到影响。我保证，即使使用此软件包（修正建议），remark 仍然会为 0.31.2 版本的所有 CommonMark 测试用例输出相同的 HTML。

이 사양 변경 제안은 한국어, 일본어, 중국어 이외의 언어에는 영향을 미치지 않습니다. 애플리케이션이나 문서에 다른 언어의 번역이나 콘텐츠가 포함되어 있어도 영향을 받지 않으므로 안심하고 본 패키지를 사용하시기 바랍니다. 본 패키지(수정안)를 사용해도 0.31.2 시점의 모든 CommonMark 테스트 케이스에서 remark가 동일한 HTML을 출력하는 것을 보장합니다.