https://github.com/giuseppelt/rehype-link-processor
rehype plugin to process links to add custom css class or attributes used by external or download links
https://github.com/giuseppelt/rehype-link-processor
markdown mdx rehype rehype-plugin unified
Last synced: about 2 months ago
JSON representation
rehype plugin to process links to add custom css class or attributes used by external or download links
- Host: GitHub
- URL: https://github.com/giuseppelt/rehype-link-processor
- Owner: giuseppelt
- License: mit
- Created: 2022-12-06T15:43:52.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-05-02T17:23:37.000Z (about 3 years ago)
- Last Synced: 2025-10-28T23:38:36.191Z (7 months ago)
- Topics: markdown, mdx, rehype, rehype-plugin, unified
- Language: TypeScript
- Homepage:
- Size: 20.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# rehype-link-processor
[rehype](https://github.com/rehypejs/rehype) plugin to process links to
- add custom css classes
- detect external, download, same-page links
- set attributes like `rel` or `target`
- add custom attributes
## Why
This package helps to decorate links usually in a markdown document where no extra attribute can be set.
Common scenarios:
- set external links to open in a new page
- decorate a link with a css class to style it, for example adding an icon next to it
- detect external links even when the url don't start with http(s)://
- detect download links
- identify links under some condition to add custom attributes
When you write links in markdown, you're limited with just the url, text and title. You cannot add custom attributes, for example a css class to style that specific link as you want.
This package helps to process and transform links.
## Installation
This is package is module. So an ESM compatible runtime is required (node 14+, deno, ...)
```bash
npm i rehype-link-processor
# or
pnpm add rehype-link-processor
# or
yarn add rehype-link-processor
```
## Integration
### Within a `unified` pipeline
Include rehype-link-processor in the pipeline:
```ts
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeLinkProcessor from "rehype-link-processor";
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeLinkProcessor)
.process("...")
```
### Within a `mdx` compilation
Include rehype-link-processor in the rehype plugins:
```ts
import {compile} from "@mdx-js/mdx";
import rehypeLinkProcessor from "rehype-link-processor";
const file = '[download:Get the pdf](/assets/article.pdf)';
await compile(file, { rehypePlugins: [rehypeLinkProcessor] });
```
### In an Astro website
Include rehype-link-processor as markdown rehype plugin in the `astro.config.ts`:
```ts
//file: astro.config.ts
import { defineConfig } from "astro/config";
import rehypeLinkProcessor from "rehype-link-processor";
export default defineConfig({
markdown: {
rehypePlugins: [rehypeLinkProcessor()]
}
);
```
## Configuration
The processor works with rules. If a rule matches, the action is applied (the link is transformed), and the processing ends.
So the rule order is important, as the first match wins.
The rules are set via the options argument:
```ts
rehypeLinkProcessor({
rules: [
// add rules here
]
})
```
This package provides some builtin rules covering common scenarios. You can also add custom rules to fit you needs.
There are three rule types:
- [Builtin](#builtin-rules): identified by a name
- [Match rule](#match-rule): defined by an `object`
- [Transform rule](#transform-rule): defined by a `function`
### Builtin rules
All builtin rules are enabled by default.
Builtin rules can be disabled with `useBuiltin` set to `false`.
```ts
rehypeLinkProcessor({
useBuiltin: false
})
```
When you disable builtin rules, you can add the ones you like manually:
```ts
rehypeLinkProcessor({
rules: [
"external" // <-- enable the external link rule
]
})
```
or your use the helper `R` when you need a configuration:
```ts
rehypeLinkProcessor({
rules: [
R.download({
skipExtension: ["html"] // exclude html to be considered a download
})
]
})
```
The builtin rules are:
- `external`
looks for external links matching when one of:
- the url starts with `http:` or `https`:
- the url starts with the prefix `external:`
- the text starts with the prefix `external:`
if matched, the resulting `a` will have the attributes:
- `class` = "external"
- `target` = "_blank"
- `rel` = "nofollow noopener"
Examples
Markdown:
`[Github](https://github.com)`
HTML:
`Github`
***
Markdown:
`[external:Discussion on Github](/discussion)`
HTML:
`Discussion on Github`
- `download`
looks for download links matching when one of:
- the url starts with `http:` or `https:` and the path ends with `.` where `ext` is [1-4] chars long (excluded: `html`, `htm`, `md`, `mdx`)
- the url starts with the prefix `download:`
- the text starts with the prefix `download:`
if matched, the resulting `a` will have the attributes:
- `class` = "download"
- `download` = the filename extracted or `true` when detected by the prefix
Examples
Markdown:
`[Download the pdf](/assets/my-article.pdf)`
HTML:
`Download the pdf`
***
Markdown:
`[download:Get the Archive](/directory?format=zip)`
HTML:
`Get the Archive`
- `email`
looks for email links matching when one of:
- the url starts with `mailto:`
- the url starts with the prefix `email:`
- the text starts with the prefix `email:`
if matched, the resulting `a` will have the attributes:
- `class` = "email"
Examples
Markdown:
`[Contact us](support@domain.com)`
HTML:
`Contact us`
***
Markdown:
`[email:Send us a mail](info@domain.com)`
HTML:
`Send us a mail`
- `same-page`
detect navigation within the same page, aka fragment navigation
- checks if the url starts with `#`
the resulting `a` will have the attributes
- `class` = "same-page"
Examples
Markdown:
`[Chapter 2](#chapter-2)`
### Match rule
A match rule, works in two steps:
- the match: where you identify the link you want to process
- the action: where you specify what transformations you want to apply
```ts
rules: [
{
match: link => link.href.startWith("mailto:"),
action: { className: "email" }
}
]
```
If the `match` returns a falsy value (`false`, `undefined`, ...). The rule is skipped.
You can specify multiple actions in an Array.
You can use the `A` helper witch provides common actions.
```ts
// rule to correct GiThuB link casing
rules: [
{
match: link => link.text?.toLowerCase() === "github"
action: [
// add the class: the link can have preexisting class
A.mergeClass("brand-link"),
// another syntax for { text: "GitHub" }
A.set("text", "GitHub")
]
}
]
```
The match function can also return an object. It will be assigned over the link, overwriting the common fields.
It's useful in a scenario where you want to apply a transformation right away in the matching step.
```ts
rules: [
{
match: link => {
if(link.href.startsWith("http:")){
return { href: link.href.replace("http:", "https:") };
}
},
action: [
A.set("target", "_blank"),
]
}
]
```
### Transform rule
With a transform rule you can analyze any like directly. The transform rule provides a `function` based syntax to process links.
With the link as input, a transform rule can return:
- a falsy value, to skip the rule
- an object, to apply the patch: the object fields overwrite the link ones
You can add a transform rule like any other rule:
```ts
{
rules: [
link => {
if (link.href?.includes("github.com")) {
return { title: "GitHub: Where this code lives" };
}
}
]
}
```
## Types
This package is built in typescript so it has full typings support.
## License
[MIT](LICENSE) © [Giuseppe La Torre](https://github.com/giuseppelt)