npm 包 markdown-it-ruby 使用教程

为了让我们的网站更加美观和易读，我们通常会添加各种效果来优化排版和阅读体验。而 ruby 注解（或称“小字注释”）则是一种常见的排版效果，它可以解释或说明一个单词或一句话中的某一个词或短语的含义或发音。那么在前端中，如何实现这样的效果呢？今天我们将介绍一个名为 markdown-it-ruby 的 npm 包，用它可以方便地为我们的网站添加 ruby 注解。

安装

我们先来安装 markdown-it-ruby：

npm install markdown-it markdown-it-ruby --save-dev

在安装 markdown-it-ruby 之前，我们还需要先安装 markdown-it，因为 markdown-it-ruby 本质上是一个插件，需要基于 markdown-it 环境进行初始化。

使用

在安装完毕后，我们需要在代码中引入这两个 npm 包：

const MarkdownIt = require('markdown-it');
const MarkdownItRuby = require('markdown-it-ruby');

接着，我们需要创建一个 markdown-it 实例，并在其中添加 markdown-it-ruby 插件：

const md = new MarkdownIt();
md.use(MarkdownItRuby);

这样，我们就可以使用 markdown-it 提供的 markdown 解析函数将 markdown 文本转化成 html 文件，并自动添加 ruby 注解。下面是一个简单的示例代码：

const text = '虽然<ruby>哥伦布<rp>(</rp><rt>Columbus</rt><rp>)</rp></ruby>发现了新大陆，<ruby>但他并不是第一个到达那里的欧洲人<rp>(</rp><rt>the first European. to have reached there</rt><rp>)</rp></ruby>。';
const html = md.render(text);
console.log(html);

执行上述代码后，我们会在控制台上看到以下的 html 代码：

虽然<ruby>哥伦布<rp>(</rp><rt>Columbus</rt><rp>)</rp></ruby>发现了新大陆，<ruby>但他并不是第一个到达那里的欧洲人<rp>(</rp><rt>the first European. to have reached there</rt><rp>)</rp></ruby>。

参数

Markdown-it-ruby 提供了一些参数配置以支持更加灵活的使用。下面是一些常用的配置参数：

• rubyParenthesis：匹配 ruby 注解中左右括号的正则表达式，默认值为 /[\uff08()]/；
• rubySeparator：匹配 ruby 注解中分隔符的正则表达式，默认值为 /[\uff0f/]/；
• rubyClass：添加到 ruby 注解上的 CSS 类名，默认值为 markdown-it-ruby；
• rubyTag：包含 ruby 注解的 HTML 标签名称，默认值为 ruby；
• rubyTextTag：包含 ruby 文本的 HTML 标签名称，默认值为 rp；
• rubyParenthesisTag：包含 ruby 注解左右括号的 HTML 标签名称，默认值为 rp。

我们可以通过修改这些参数的值来达到不同的排版效果。

md.use(MarkdownItRuby, {
  rubyParenthesis: /[\uff08\uff09]/,
  rubySeparator: /[\uff0f]/,
  rubyClass: 'my-ruby',
  rubyTag: 'ruby',
  rubyTextTag: 'rt',
  rubyParenthesisTag: 'rp'
});

总结

markdown-it-ruby 给我们的前端排版带来了非常方便和高效的解决方法，通过简单的配置和代码实现，我们就可以实现各式各样的 ruby 注解效果，提升网站的可读性和美观度。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600562ca81e8991b448e010f