Add icons to external links

Using a hast plugin, you can identify and modify links in your Markdown files that point to external sites. This example adds an icon to the end of each external link, so that visitors will know they are leaving your site.

Prerequisites

• An Astro project using Markdown for content pages.

Recipe

Sätteri

1. Install both @astrojs/markdown-satteri and satteri:

   npm

   npm install @astrojs/markdown-satteri satteri

   pnpm

   pnpm add @astrojs/markdown-satteri satteri

   Yarn

   yarn add @astrojs/markdown-satteri satteri

2. Create a Sätteri hast plugin that adds an icon if the link starts with http:

   src/hast/hast-external-links.ts

   import { defineHastPlugin } from 'satteri';
   
   export const hastExternalLinks = defineHastPlugin({
     name: "hast-external-links",
     element: {
       filter: ["a"],
       visit(node, context) {
         if (node.properties.href?.startsWith("http")) {
           context.appendChild(node, {
             type: "element",
             tagName: "span",
             properties: { ariaHidden: "true" },
             children: [
               {
                 type: "text",
                 value: "🔗",
               },
             ],
           });
         }
       },
     },
   });

3. Configure the plugin in your astro.config.mjs file.

   Import satteri() and define it as the Markdown processor to add custom Sätteri plugins. Then, pass to hastPlugins an array containing your imported hastExternalLinks plugin.

   astro.config.mjs

   import { satteri } from '@astrojs/markdown-satteri';
   import { defineConfig } from 'astro/config';
   import { hastExternalLinks } from './src/hast/hast-external-links';
   
   export default defineConfig({
     markdown: {
       processor: satteri({
         hastPlugins: [hastExternalLinks],
       }),
     },
   });

Unified

1. Install both the rehype-external-links plugin and @astrojs/markdown-remark.

   npm

   npm install rehype-external-links @astrojs/markdown-remark

   pnpm

   pnpm add rehype-external-links @astrojs/markdown-remark

   Yarn

   yarn add rehype-external-links @astrojs/markdown-remark

2. Configure the plugin in your astro.config.mjs file.

   Import unified() and define it as the Markdown processor to support remark plugins. Then, pass to rehypePlugins an array containing your imported rehypeExternalLinks plugin and an options object with a content property. Set this property’s type to text if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property type to raw.

   astro.config.mjs

   import { unified } from '@astrojs/markdown-remark';
   import { defineConfig } from 'astro/config';
   import rehypeExternalLinks from 'rehype-external-links';
   
   export default defineConfig({
     markdown: {
       processor: unified({
         rehypePlugins: [
           [
             rehypeExternalLinks,
             {
               content: { type: 'text', value: ' 🔗' }
             }
           ],
         ]
       }),
     },
   });