{"id":15478424,"url":"https://github.com/giuseppelt/rehype-link-processor","last_synced_at":"2026-04-08T22:31:04.591Z","repository":{"id":64411814,"uuid":"575029135","full_name":"giuseppelt/rehype-link-processor","owner":"giuseppelt","description":"rehype plugin to process links to add custom css class or attributes used by external or download links","archived":false,"fork":false,"pushed_at":"2023-05-02T17:23:37.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-28T23:38:36.191Z","etag":null,"topics":["markdown","mdx","rehype","rehype-plugin","unified"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giuseppelt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-06T15:43:52.000Z","updated_at":"2025-05-09T18:55:13.000Z","dependencies_parsed_at":"2024-11-14T16:24:41.867Z","dependency_job_id":"6dcb0604-726f-4496-b657-26ec10efe8d1","html_url":"https://github.com/giuseppelt/rehype-link-processor","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"a78e235cd37a0aa37a1e7411fc91e4da1543b56e"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/giuseppelt/rehype-link-processor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Frehype-link-processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Frehype-link-processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Frehype-link-processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Frehype-link-processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giuseppelt","download_url":"https://codeload.github.com/giuseppelt/rehype-link-processor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Frehype-link-processor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31577444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","mdx","rehype","rehype-plugin","unified"],"created_at":"2024-10-02T04:04:11.579Z","updated_at":"2026-04-08T22:31:04.574Z","avatar_url":"https://github.com/giuseppelt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rehype-link-processor\n[rehype](https://github.com/rehypejs/rehype) plugin to process links to\n- add custom css classes\n- detect external, download, same-page links\n- set attributes like `rel` or `target`\n- add custom attributes\n\n## Why\nThis package helps to decorate links usually in a markdown document where no extra attribute can be set.\n\nCommon scenarios:\n- set external links to open in a new page\n- decorate a link with a css class to style it, for example adding an icon next to it\n- detect external links even when the url don't start with http(s)://\n- detect download links\n- identify links under some condition to add custom attributes\n\n\nWhen 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.\n\nThis package helps to process and transform links.\n\n## Installation\nThis is package is module. So an ESM compatible runtime is required (node 14+, deno, ...)\n```bash\nnpm i rehype-link-processor\n# or\npnpm add rehype-link-processor\n# or\nyarn add rehype-link-processor\n```\n\n## Integration\n### Within a `unified` pipeline\nInclude rehype-link-processor in the pipeline:\n```ts \nimport { unified } from \"unified\";\nimport remarkParse from \"remark-parse\";\nimport remarkRehype from \"remark-rehype\";\nimport rehypeLinkProcessor from \"rehype-link-processor\";\n\nconst file = await unified()\n  .use(remarkParse)\n  .use(remarkRehype)\n  .use(rehypeLinkProcessor)\n  .process(\"...\")\n\n```\n\n### Within a `mdx` compilation\nInclude rehype-link-processor in the rehype plugins:\n```ts \nimport {compile} from \"@mdx-js/mdx\";\nimport rehypeLinkProcessor from \"rehype-link-processor\";\n\nconst file = '[download:Get the pdf](/assets/article.pdf)';\n\nawait compile(file, { rehypePlugins: [rehypeLinkProcessor] });\n```\n\n### In an Astro website\nInclude rehype-link-processor as markdown rehype plugin in the `astro.config.ts`:\n```ts \n//file: astro.config.ts\nimport { defineConfig } from \"astro/config\";\nimport rehypeLinkProcessor from \"rehype-link-processor\";\n\nexport default defineConfig({\n  markdown: {\n    rehypePlugins: [rehypeLinkProcessor()]\n  }\n);\n```\n\n## Configuration\nThe processor works with rules. If a rule matches, the action is applied (the link is transformed), and the processing ends.\n\nSo the rule order is important, as the first match wins.\n\nThe rules are set via the options argument:\n```ts\nrehypeLinkProcessor({\n  rules: [\n    // add rules here\n  ]\n})\n```\n\nThis package provides some builtin rules covering common scenarios. You can also add custom rules to fit you needs.\n\nThere are three rule types:\n- [Builtin](#builtin-rules): identified by a name\n- [Match rule](#match-rule): defined by an `object`\n- [Transform rule](#transform-rule): defined by a `function`\n\n### Builtin rules\nAll builtin rules are enabled by default.\n\nBuiltin rules can be disabled with `useBuiltin` set to `false`.\n```ts\nrehypeLinkProcessor({\n  useBuiltin: false\n})\n```\nWhen you disable builtin rules, you can add the ones you like manually:\n```ts\nrehypeLinkProcessor({\n  rules: [\n    \"external\"   // \u003c-- enable the external link rule\n  ]\n})\n```\nor your use the helper `R` when you need a configuration:\n```ts\nrehypeLinkProcessor({\n  rules: [\n    R.download({\n      skipExtension: [\"html\"] // exclude html to be considered a download\n    })\n  ]\n})\n```\n\nThe builtin rules are:\n- `external`\n  \n  looks for external links matching when one of:\n    - the url starts with `http:` or `https`:\n    - the url starts with the prefix `external:`\n    - the text starts with the prefix `external:`\n  \n  if matched, the resulting `a` will have the attributes:\n    - `class` = \"external\"\n    - `target` = \"_blank\"\n    - `rel` = \"nofollow noopener\"\n\n  \u003cbr /\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n  Markdown: \u003cbr /\u003e\n  `[Github](https://github.com)`\n  \n  HTML: \u003cbr /\u003e\n  `\u003ca href=\"https://github.com\" class=\"external\" target=\"_blank\" rel=\"nofollow noopener\"\u003eGithub\u003ca\u003e`\n\n  ***\n  Markdown: \u003cbr /\u003e\n  `[external:Discussion on Github](/discussion)`\n\n  HTML:\u003cbr /\u003e\n  `\u003ca href=\"/discussion\" class=\"external\" target=\"_blank\" rel=\"nofollow noopener\"\u003eDiscussion on Github\u003c/a\u003e`\n  \u003c/details\u003e\n  \u003cbr /\u003e\n\n\n- `download`\n  \n  looks for download links matching when one of:\n    - the url starts with `http:` or `https:` and the path ends with `.\u003cext\u003e` where `ext` is [1-4] chars long (excluded: `html`, `htm`, `md`, `mdx`)\n    - the url starts with the prefix `download:`\n    - the text starts with the prefix `download:`\n  \n  if matched, the resulting `a` will have the attributes:\n    - `class` = \"download\"\n    - `download` = the filename extracted or `true` when detected by the prefix\n\n  \u003cbr /\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n  Markdown: \u003cbr /\u003e\n  `[Download the pdf](/assets/my-article.pdf)`\n\n  HTML: \u003cbr /\u003e\n  `\u003ca download=\"my-article.pd\" href=\"/assets/my-article.pdf\" class=\"download\"\u003eDownload the pdf\u003ca\u003e`\n  ***\n  Markdown: \u003cbr /\u003e\n  `[download:Get the Archive](/directory?format=zip)`\n\n  HTML: \u003cbr /\u003e\n  `\u003ca download href=\"/directory?format=zip\" class=\"download\"\u003eGet the Archive\u003c/a\u003e`\n\n  \u003c/details\u003e\n  \u003cbr /\u003e\n\n\n- `email`\n  \n  looks for email links matching when one of:\n    - the url starts with `mailto:`\n    - the url starts with the prefix `email:`\n    - the text starts with the prefix `email:`\n  \n  if matched, the resulting `a` will have the attributes:\n    - `class` = \"email\"\n\n  \u003cbr /\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n  Markdown: \u003cbr /\u003e\n  `[Contact us](support@domain.com)`\n\n  HTML: \u003cbr /\u003e\n  `\u003ca href=\"mailto:support@domain.com\" class=\"email\"\u003eContact us\u003ca\u003e`\n  ***\n  Markdown: \u003cbr /\u003e\n  `[email:Send us a mail](info@domain.com)`\n\n  HTML: \u003cbr /\u003e\n  `\u003ca href=\"mailto:info@domain.com\" class=\"email\"\u003eSend us a mail\u003ca\u003e`\n\n  \u003c/details\u003e\n  \u003cbr /\u003e\n\n\n- `same-page`\n\n  detect navigation within the same page, aka fragment navigation\n  - checks if the url starts with `#`\n  \n  the resulting `a` will have the attributes\n  - `class` = \"same-page\"\n\n  \u003cbr /\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\n\n  Markdown: \u003cbr /\u003e\n  `[Chapter 2](#chapter-2)`\n\n  HTML: \u003cbr /\u003e\n  `\u003ca href=\"#chapter-2\" class=\"same-page\"\u003eChapter 2\u003ca\u003e`\n\n  \u003c/details\u003e\n  \u003cbr /\u003e\n\n### Match rule\nA match rule, works in two steps:\n- the match: where you identify the link you want to process\n- the action: where you specify what transformations you want to apply\n\n```ts\nrules: [\n  {\n    match: link =\u003e link.href.startWith(\"mailto:\"),\n    action: { className: \"email\" }\n  }\n]\n```\n\nIf the `match` returns a falsy value (`false`, `undefined`, ...). The rule is skipped.\n\nYou can specify multiple actions in an Array.\n\nYou can use the `A` helper witch provides common actions.\n```ts\n// rule to correct GiThuB link casing\nrules: [\n  {\n    match: link =\u003e link.text?.toLowerCase() === \"github\"\n    action: [\n      // add the class: the link can have preexisting class\n      A.mergeClass(\"brand-link\"),  \n      // another syntax for { text: \"GitHub\" }\n      A.set(\"text\", \"GitHub\")\n    ]\n  }\n]\n```\n\nThe match function can also return an object. It will be assigned over the link, overwriting the common fields.\n\nIt's useful in a scenario where you want to apply a transformation right away in the matching step.\n```ts\nrules: [\n  {\n    match: link =\u003e {\n      if(link.href.startsWith(\"http:\")){\n        return { href: link.href.replace(\"http:\", \"https:\") };\n      }\n    },\n    action: [\n      A.set(\"target\", \"_blank\"),  \n    ]\n  }\n]\n```\n\n### Transform rule\nWith a transform rule you can analyze any like directly. The transform rule provides a `function` based syntax to process links.\n\nWith the link as input, a transform rule can return:\n- a falsy value, to skip the rule\n- an object, to apply the patch: the object fields overwrite the link ones\n\nYou can add a transform rule like any other rule:\n```ts\n{\n  rules: [\n    link =\u003e {\n      if (link.href?.includes(\"github.com\")) {\n        return { title: \"GitHub: Where this code lives\" };\n      }\n    }\n  ]\n}\n```\n\n## Types\nThis package is built in typescript so it has full typings support.\n\n## License\n[MIT](LICENSE) © [Giuseppe La Torre](https://github.com/giuseppelt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuseppelt%2Frehype-link-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiuseppelt%2Frehype-link-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuseppelt%2Frehype-link-processor/lists"}