remark-interactive-words

remark-interactive-words is a plugin for remark. It's built to facilitate Aided Reading (AR) on digital devices.

Intro

Designed to transform markdown by replacing words with interactive, clickable links with a #slug for programmatic use, remark-interactive-words is developed by Russ Fugal for SARAs Books LLC to support Aided Reading (AR) automation. This plugin integrates seamlessly with the remark ecosystem.

• to learn markdown, see this cheatsheet and tutorial
• for more about the remark ecosystem, see unifiedjs.com
• to help, see contribute or sponsor below

Contents

• What is this?
• When should I use this?
• API
  • remark().use(remarkToc, options)
  • slug
  • interface InteractiveWordsOptions
• Examples
  • Example: 'This is a test.'
• Syntax
• Syntax tree
• Types
• Contribute
• Sponsor
• License

What is this?

unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is a specification for representing markdown in a syntax tree. It implements unist. It can represent several flavors of markdown, such as CommonMark and GitHub Flavored Markdown.

remark-interactive-words leverages mdast, inspecting and modifying the AST to create its interactive functionality. This plugin works with markdown as structured data.

When should I use this?

remark-interactive-words is a plugin for remark. It's built to facilitate Aided Reading (AR) on digital devices. You can easily integrate it with your existing remark plugins to achieve word-wise interactivity and functionality in your markdown documents.

API

To install the remark-interactive-words plugin, run the following command in your terminal:

1npm install remark-interactive-words

The default export is remarkInteractiveWords.

remark().use(remarkInteractiveWords, options)

Generate markdown with linked words. Looks for all Text Nodes and transforms all but descendants of excludingNodes.

1const excludingNodes = [
2    'code',
3    'inlineCode',
4    'link',
5    'linkReference',
6    'html'
7]

slug

remarkInteractiveWords matches words with wordRegex and transforms them to transformTo Nodes with a #slug for programatic use.

1const wordRegex = /([a-z]+['’][a-z]+)|[a-z]{2,}/gi;
2
3function getWordSlug(word: string): string {
4    return word.toLowerCase().replace("’", "'");
5}

interface InteractiveWordsOptions

Via the options object, you can customize the behavior of remark-interactive-words. Specific words can be excluded from transformation by passing an array of words to exceptions. You can also customize the transformation by passing a helper function. The helper function is called with a HelperInput object and should return an array of HelperResult objects.

1interface InteractiveWordsOptions {
2  transformTo: 'link' | 'linkReference'
3  exceptions?: string[] // array of words to exclude from transformation
4  helper?: (input: HelperInput) => HelperResult[]
5}
6
7interface HelperInput {
8    input: string;
9    exceptions?: string[];
10}
11
12interface HelperResult {
13    text: string;
14    transform: boolean;
15    wordSlug?: string;
16}

Examples

Example: 'This is a test.'

After installation, you can require and use remark-interactive-words as follows:

1import { remark } from 'remark';
2import remarkInteractiveWords from 'remark-interactive-words';
3import { InteractiveWordsOptions } from 'remark-interactive-words';
4
5const options: InteractiveWordsOptions = {
6    transformTo: 'link'
7};
8
9const input = 'This is a test.';
10const expectedOutput = '[This](#this) [is](#is) a [test](#test).';
11
12const processor = remark().use(remarkInteractiveWords);
13const output = processor.processSync(input);
14
15expect(String(output)).toEqual(expectedOutput);

Syntax

Syntax tree

Types

Contribute

We welcome contributions to remark-interactive-words. Please see the contributing guidelines for more information.

Sponsor

remark-interactive-words is an open-source project that is supported by the community. If you find it useful, please consider supporting us via GitHub Sponsors.

License

MIT © Russ Fugal