Automated Route Generation

rehype-smart-links needs to know the valid routes in your site to correctly identify broken links. This tutorial explains how to use the built-in command-line tool to generate a route mapping file and use it correctly in your configuration.

Why Do You Need a Routes File?

When rehype-smart-links processes your Markdown content, it needs to verify if internal links point to valid pages. To achieve this, the plugin needs a list of all valid routes in your site. By automatically generating this list, you can:

1. Ensure internal links are highlighted correctly
2. Identify broken links
3. Prevent users from visiting non-existent pages

Using the Command-Line Tool to Generate Routes

rehype-smart-links provides a built-in command-line tool that makes the route generation process simple.

Setting Up Build Commands

Add the following script to your package.json:

{
  "scripts": {
    "build:with-routes": "astro build && rehype-smart-links build && astro build"
  }
}

This command will:

1. First build your site
2. Scan the build output directory and generate the routes file
3. Build your site again using the generated routes information

Configuring the Routes File Path

By default, the CLI tool generates a .smart-links-routes.json file in your project root. Make sure to use the same path in your rehype-smart-links configuration:

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

export default defineConfig({
  markdown: {
    rehypePlugins: [[rehypeSmartLinks, {
      // This path must match the file path generated by the CLI tool
      routesFile: './.smart-links-routes.json',
      // Other configuration...
    }]]
  }
});

Important note: If you use a custom output path (--output option) in the CLI, make sure to set the routesFile in your plugin configuration to the same path, otherwise the plugin won’t find the correct routes information.

Customizing CLI Options

The CLI tool supports various configuration options:

Options:
  -d, --dir <path>        Build directory path (default: "./dist")
  -o, --output <path>     Output path for the routes file (default: "./.smart-links-routes.json")
  -a, --all               Include all file types (default: false)
  -e, --extensions <ext>  File extensions to include (default: ["html"])
  -h, --help              Display help information

For example, to include more file types:

# Generate a route map that includes all files
rehype-smart-links build --all

# Specify particular file types
rehype-smart-links build --extensions html md pdf

# Customize the output path (remember to use the same path in your plugin configuration)
rehype-smart-links build --output ./src/routes.json

Using in CI/CD Environments

In hosting services like Vercel, Netlify, etc., you can modify the build command:

# Vercel or Netlify build command
npm run build:with-routes

Integrating with Other Build Tools

rehype-smart-links route generation can be used with any build tool:

# Vite project
vite build && rehype-smart-links build --dir dist && vite build

# 11ty project
eleventy && rehype-smart-links build --dir _site && eleventy

Troubleshooting

If your links are not being recognized correctly, check:

1. If the routes file was successfully generated (check your project root or custom path)
2. If the routesFile path in your plugin configuration matches the generated file path
3. If the build directory (--dir) is correctly set to your build output directory