remark-autolinker

Contents

• What is this?
• When should I use this?
• Install
• Usage
• Direct Usage
• Configuration
• Contributing
• Thanks
• License

What is this?

This plugin is part of the remark plugin infrastructure used by components such as mdsvex. Using markdown to write your content is a nice and convenient way to edit your content. Typically your writing content for a certain domain so you obviously would repeat several links across all your pages. Although unproblematic this plugin provides you with a lazy solution for this. It allows to setup a global configuration providing terms that shall be used to generate links. Here is a little example:

---
title: example
---
My main programming language is Java.

Using a corresponding configuration you can automatically link the term Java to generate the following markdown:

---
title: example
---
My main programming language is [Java](https://www.java.com/de/).

Obviously it's up to you which terms should be linked automatically.

When should I use this?

Whenever you like to conveniently generate links. This plugin isn't necessary but it's very helpful do stop repeating yourself.

Install

This package is ESM only. In Node.js (version 18+), install with pnpm:

pnpm i -D @kasisoft/remark-autolinker

Usage

• Setup your Svelte project and install mdsvex (see mdsvexdocs)
• Your project will now contain a file named mdsvex.config.js.
  • Import the plugin:

    import { remarkAutolinker } from '@kasisoft/remark-autolinker';

  • Update the array of remark plugins with a configuration:

    // RemarkAutolinkerOptions
    const myconfig = {
        debug: ['RootBefore', 'RootAfter'],
        all: false,
        caseInsensitive: false,
        links: [
            { key: 'Java', link: 'https://www.java.com/de/' },
            ...
        ],
    };
    const config = defineConfig({
        ...
        remarkPlugins: [
            [remarkAutolinker, myconfig]
        ],
        ...
    });

Direct Usage

It's possible to use the autolinking functionality directly like this:

• Import the functionality:

  import { autolinkText } from '@kasisoft/remark-autolinker';

• Run the transformation of a text:

    // RemarkAutolinkerOptions
    const myconfig = {
        debug: ['RootBefore', 'RootAfter'],
        all: false,
        caseInsensitive: false,
        links: [
            { key: 'Java', link: 'https://www.java.com/de/' },
            ...
        ],
    };
  const mytext: string = 'Some text...';
  const transformed: (string|Link)[] = autolinkText(mytext, myconfig);
  // each autolinked element is of type Link whereas non-matching
  // elements remain simple text.

Configuration

The configuration is fully typed using Typescript. RemarkAutolinkerOptions is defined as followed:

export interface Link {

    /* The term to be replaced by a Link */
    key: string,

    /* The link itself */
    link: string,

} /* ENDINTERFACE */

export interface RemarkAutolinkerOptions {

    /* Debug.{None, Default, RootBefore, RootAfter, All}
     * It's okay to use a list of string values for the debugging levels.
     * For instance: ['RootBefore', 'RootAfter']
     */
    debug           : Debug|'None'|'Default'|'RootBefore'|'RootAfter'|'All'|string[];

    /* By default only the first occurrance will be changed into a link.
     * If enabled all occurrences will be changed.
     */
    all             : boolean;

    /* By default the replacement requires a case sensitive match.
     * If enabled it will match independently of case sensitivity.
     */
    caseInsensitive : boolean;

    /* This is the list of links to define the terms that should be linked automatically. */
    links           : Link[];

} /* ENDINTERFACE */

• debug : Debug - Combine flags of Debug in order to generate debug statements:
  • Debug.None: no output (just a convenience value)
  • Debug.Default: some basic output
  • Debug.RootBefore: prints the ast before the transformation
  • Debug.RootAfter: prints the ast after the transformation
  • Debug.All: enables all outputs (convenience value)
  • Using an array of strings representing these debug settings is also possible. For instance:
    • ['RootBefore', 'RootAfter']
• all : Enables the automatic linking for all occurrences within the text.
• caseInsensitive : Enables case insensitive matching.
• links : The list of links to be used for the automatic linking.

Contributing

If you want to contribute I'm happy for any kind of feedback or bug reports. Please create issues and pull requests as you like but be aware that it may take some time for me to react.

Thanks

• Svelte - For providing a great, fast and easy comprehensible framework.
• MSDVEX - For the nice intergration of Markdown in Svelte
• remark - For a great platform to modify/transform the content.

License

MIT © Kasisoft.com - [email protected]