dahlia / markdown-it-jsr-ref

A markdown-it plugin that turns backtick-enclosed symbols into links to JSR API references

markdown-it-jsr-ref

This is a markdown-it plugin that turns backtick-enclosed symbols into links to JSR API references. For example, the following Markdown snippet:

The `jsrRef()` function takes `Options` object as its argument.

will be transformed into:

The [`jsrRef()`] function takes [`Options`] object as its argument.

[`jsrRef()`]: https://jsr.io/@hongminhee/[email protected]/doc/~/jsrRef
[`Options`]: https://jsr.io/@hongminhee/[email protected]/doc/~/Options

and rendered as:

The jsrRef() function takes Options object as its argument.

Usage

Since this plugin needs to download the index data from JSR, it requires an asynchronous initialization. After once a plugin instance is created, you don't need asynchronous operations anymore:

import MarkdownIt from "markdown-it";
import { jsrRef } from "markdown-it-jsr-ref";

const md = new MarkdownIt();
md.use(await jsrRef({
  package: "@hongminhee/markdown-it-jsr-ref",
  version: "0.1.0",  // "stable" or "unstable" is also available
  cachePath: ".jsr-cache.json",  // Optional, but highly recommended
  progress: (complete, total) => { // Optional
    console.log(`Downloading JSR index: ${complete}/${total}`);
  }
}))

Syntax

The plugin recognizes backtick-enclosed symbols as JSR references.

- `ClassName`
- `InterfaceName`
- `TypeAliasName`
- `functionName()`
- `ClassName.accessorName`
- `ClassName.methodName()`
- `Interface.propertyName`
- `Interface.callSignatureName()`

For methods and properties, you can prefix them with a tilde (~) to hide the class or interface name after rendering:

- `~ClassName.accessorName`
- `~ClassName.methodName()`
- `~Interface.propertyName`
- `~Interface.callSignatureName()`