Quick Start Guide

rehype-smart-links is a rehype plugin that adds smart functionality to Markdown links. This guide will help you quickly install and configure the plugin.

Installation

Install the plugin using your preferred package manager:

# Using npm
npm install rehype-smart-links

# Using yarn
yarn add rehype-smart-links

# Using pnpm
pnpm add rehype-smart-links

Basic Configuration

Using with Astro

Add the plugin to your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import rehypeSmartLinks from 'rehype-smart-links';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      // Basic usage (default settings)
      rehypeSmartLinks,
      
      // Or with custom options
      [rehypeSmartLinks, {
        internalLinkClass: 'internal-link',
        brokenLinkClass: 'broken-link',
        externalLinkClass: 'external-link',
        routesFile: './.smart-links-routes.json', // Path to routes file
        includeAllFiles: false,  // Whether to include all file types
      }]
    ]
  }
});

Using with Next.js

In Next.js projects, you can use MDX and rehype plugins:

// next.config.js
const withMDX = require('@next/mdx')({
  options: {
    rehypePlugins: [
      require('rehype-smart-links')
    ]
  }
})

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
})

Using with Gatsby

Configure in Gatsby projects:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        rehypePlugins: [
          require('rehype-smart-links')
        ],
      },
    },
  ],
}

Adding Styles

The plugin adds the following CSS classes for different types of links:

internal-link: Applied to internal links (pointing to pages within your site)
broken-link: Applied to broken internal links (pointing to non-existent pages)
external-link: Applied to external links (pointing to other websites)

You can add styles in your global CSS file:

/* Internal link styles */
.internal-link {
  color: #3b82f6;
  position: relative;
}

.internal-link::after {
  content: '';
  position: absolute;
  width: 100%;
  height: 1px;
  bottom: -2px;
  left: 0;
  background-color: currentColor;
  transform: scaleX(0);
  transform-origin: left;
  transition: transform 0.3s ease;
}

.internal-link:hover::after {
  transform: scaleX(1);
}

/* Broken link styles */
.broken-link {
  color: #ef4444;
  text-decoration: line-through;
  opacity: 0.8;
}

/* External link styles */
.external-link {
  color: #10b981;
  position: relative;
  padding-right: 1.2em;
}

.external-link::after {
  content: '↗';
  position: absolute;
  right: 0;
  font-size: 0.8em;
}

Advanced Configuration Options

rehype-smart-links provides multiple configuration options:

Option	Type	Default	Description
`internalLinkClass`	`string`	`'internal-link'`	CSS class applied to internal links
`brokenLinkClass`	`string`	`'broken-link'`	CSS class applied to broken links
`externalLinkClass`	`string`	`'external-link'`	CSS class applied to external links
`content`	`object`	`{ type: 'text', value: '↗' }`	Content added to external links
`contentClass`	`string`	`'external-icon'`	CSS class applied to the external link icon
`routesFile`	`string`	`'./.smart-links-routes.json'`	Path to the routes mapping file (should match CLI output location)
`includeAllFiles`	`boolean`	`false`	Whether to include all files in route checks
`target`	`string`	`'_blank'`	Target attribute for external links
`rel`	`string`	`'noopener noreferrer'`	Rel attribute for external links
`externalLinkAttributes`	`object`	`{ target: '_blank', rel: 'noopener noreferrer' }`	HTML attributes applied to external links
`wrapperTemplate`	`function`		Custom link wrapper template function

Check out Advanced Demo for more examples of customization options.