Dynamic Route Manager for Wiki-Style Backlinks

Summary

Implemented a flexible route manager system for wiki-style backlinks that maps content paths to web routes, allowing for dynamic configuration of routing rules without code changes.

Why Care

This system solves a critical navigation issue where content paths (e.g., vocabulary/Software Development) needed to be mapped to specific web routes (e.g., /more-about/software-development). The implementation provides a Single Source of Truth for route transformations, making the site's internal linking system more maintainable and configurable through a user-friendly admin interface.

Implementation

Changes Made

  • Created a centralized route manager module:
    • /site/src/utils/routing/routeManager.ts - Core route transformation logic and API
  • Updated the backlinks plugin to use the route manager:
    • /site/src/utils/markdown/remark-backlinks.ts - Modified to use the new route transformation system
  • Added an admin interface for managing route mappings:
    • /site/src/components/admin/RouteManager.astro - UI component for managing mappings
    • /site/src/pages/admin/route-manager.astro - Admin page that hosts the component
  • Implemented an API endpoint for programmatic management:
    • /site/src/pages/api/route-mappings.ts - RESTful API for route mappings
  • Updated documentation:
    • /content/lost-in-public/prompts/render-logic/Conditional-Logic-for-Content.md - Added detailed documentation of the implementation

Technical Details

Route Manager Module

The route manager (/site/src/utils/routing/routeManager.ts) provides a centralized system for mapping content paths to web routes:
typescript 
// Core data structure for route mappings
interface RouteMapping {
  contentPath: string;  // Content directory path prefix
  routePath: string;    // Corresponding web route
}

// Default mappings with common content types
const defaultRouteMappings: RouteMapping[] = [
  {
    contentPath: 'vocabulary',
    routePath: 'more-about'
  },
  {
    contentPath: 'lost-in-public/prompts',
    routePath: 'prompts'
  }
];

// Core transformation function
export function transformContentPathToRoute(path: string): string {
  // Normalize the path and apply mappings
  // ...implementation details
}

// API for managing mappings
export function addRouteMapping(contentPath: string, routePath: string): void {
  // Add or update a mapping
  // ...implementation details
}

export function removeRouteMapping(contentPath: string): void {
  // Remove a mapping
  // ...implementation details
}

export function getAllRouteMappings(): RouteMapping[] {
  // Get all mappings (default + custom)
  // ...implementation details
}
Updated the remark-backlinks plugin (/site/src/utils/markdown/remark-backlinks.ts) to use the route manager:
typescript 
import { transformContentPathToRoute } from '../routing/routeManager';

// Within the transformer function:
const transformedPath = transformContentPathToRoute(path);

Admin Interface

Created a component (/site/src/components/admin/RouteManager.astro) and admin page (/site/src/pages/admin/route-manager.astro) for managing route mappings with a user-friendly interface that includes:
  • Table view of current mappings
  • Form for adding new mappings
  • Buttons for removing existing mappings
  • Status messages for operation feedback

API Endpoint

Implemented a RESTful API (/site/src/pages/api/route-mappings.ts) with:
  • GET endpoint to retrieve all mappings
  • POST endpoint to add or remove mappings
  • Input validation and error handling

Integration Points

  • Markdown Processing Pipeline: The route manager integrates with the Astro markdown processing pipeline through the remark-backlinks plugin.
  • Admin System: The route manager admin page extends the site's admin capabilities.
  • Content Authoring: Content authors can now use wiki-style links with confidence that they will be properly routed.

Documentation

The implementation is documented in:
  • /content/lost-in-public/prompts/render-logic/Conditional-Logic-for-Content.md - Detailed technical documentation
  • Inline code comments throughout all implemented files

Usage Examples

Before Implementation:
markdown 
[[vocabulary/Software Development]] → /content/vocabulary/software-development
After Implementation:
markdown 
[[vocabulary/Software Development]] → /more-about/software-development
The route manager can be used in three ways:
  1. Through the admin UI at /admin/route-manager
  2. Programmatically via the API
  3. Directly in code by importing the route manager functions