CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-astrojs--markdown-remark

Astro's internal markdown processing library that provides a unified markdown processor built on remark and rehype ecosystem plugins with syntax highlighting, frontmatter parsing, and image processing capabilities.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

remark-plugins.mddocs/

Remark Plugins

Built-in remark plugins for image collection and other content processing tasks within the markdown processing pipeline.

Capabilities

Collect Images Plugin

Collects local and remote image paths from markdown content for processing and optimization.

/**
 * Collect local and remote image paths from markdown
 * @param opts - Image processing configuration options
 * @returns Remark plugin function
 */
function remarkCollectImages(
  opts?: AstroMarkdownProcessorOptions['image']
): Plugin<[AstroMarkdownProcessorOptions['image']?], mdast.Root>;

Usage Examples:

import { createMarkdownProcessor, remarkCollectImages } from "@astrojs/markdown-remark";

// Using in processor configuration (automatic by default)
const processor = await createMarkdownProcessor({
  remarkPlugins: [
    [remarkCollectImages, {
      domains: ['example.com', 'cdn.example.com'],
      remotePatterns: [
        {
          protocol: 'https',
          hostname: '**.github.com'
        },
        {
          protocol: 'https', 
          hostname: 'images.unsplash.com'
        }
      ]
    }]
  ]
});

const result = await processor.render(`
# My Blog Post

![Local screenshot](./screenshots/app.png)
![User avatar](../assets/avatar.jpg)
![Remote image](https://example.com/hero.jpg)
![GitHub image](https://github.com/user/repo/raw/main/image.png)
![Disallowed remote](https://random-site.com/image.png)

[Link with image]: ./assets/linked-image.png
`);

console.log(result.metadata.localImagePaths);
// ['./screenshots/app.png', '../assets/avatar.jpg', './assets/linked-image.png']

console.log(result.metadata.remoteImagePaths);
// ['https://example.com/hero.jpg', 'https://github.com/user/repo/raw/main/image.png']

// The disallowed remote image is not included in remoteImagePaths

Features:

  • Local Image Detection: Identifies relative paths as local images
  • Remote Image Validation: Checks remote URLs against allowed domains and patterns
  • Image Reference Support: Handles both direct images and image references
  • URL Decoding: Properly decodes URLs for consistent processing
  • Domain Filtering: Only includes remote images from allowed domains
  • Pattern Matching: Supports flexible hostname patterns with wildcards

Image Configuration Options

Configuration options for image processing and validation.

interface ImageOptions {
  /** Array of allowed domains for remote images */
  domains?: string[];
  /** Array of remote patterns for flexible hostname matching */
  remotePatterns?: RemotePattern[];
}

interface RemotePattern {
  /** Hostname pattern with wildcard support */
  hostname?: string;
  /** Optional pathname pattern */
  pathname?: string;
  /** Protocol to match (without trailing colon) */
  protocol?: string;
  /** Optional port number */
  port?: string;
}

Usage Examples:

import { createMarkdownProcessor } from "@astrojs/markdown-remark";

const processor = await createMarkdownProcessor({
  image: {
    // Simple domain allowlist
    domains: [
      'example.com',
      'www.example.com',
      'cdn.example.com',
      'images.unsplash.com'
    ],
    
    // Pattern-based matching
    remotePatterns: [
      // Allow all GitHub domains
      {
        protocol: 'https',
        hostname: '**.github.com'
      },
      
      // Allow specific subdomain patterns
      {
        protocol: 'https',
        hostname: 'img*.example.com'
      },
      
      // Allow with specific port
      {
        protocol: 'http',
        hostname: 'localhost',
        port: '3000'
      },
      
      // Allow with pathname pattern
      {
        protocol: 'https',
        hostname: 'api.example.com',
        pathname: '/images/**'
      }
    ]
  }
});

Image Detection Logic

The plugin follows specific logic for categorizing images:

  1. URL Parsing: Attempts to parse the image source as a URL

  2. Local vs Remote:

    • If parseable as URL → check against domain/pattern allowlist
    • If not parseable and doesn't start with / → treat as local
    • If starts with / → treat as absolute path (not collected)

  3. Validation:

    • Local images: Always collected
    • Remote images: Only collected if domain/pattern matches
    • Invalid URLs: Ignored

Examples:

// Local images (collected)
![Image](./image.png)           // Relative path
![Image](../assets/image.jpg)   // Parent directory
![Image](images/photo.gif)      // Subdirectory

// Absolute paths (not collected)
![Image](/static/image.png)     // Root-relative

// Remote images (collected if allowed)
![Image](https://example.com/image.jpg)     // If example.com in domains
![Image](https://cdn.github.com/img.png)   // If **.github.com pattern exists

// Invalid/disallowed (ignored)
![Image](https://random.com/img.jpg)        // If random.com not allowed
![Image](not-a-url)                         // Invalid URL format

Integration with Image Processing

The collected image paths are used by downstream processing:

const result = await processor.render(markdown);

// Access collected paths
const localImages = result.metadata.localImagePaths;
const remoteImages = result.metadata.remoteImagePaths;

// These are later used by:
// 1. rehypeImages plugin for optimization metadata
// 2. Astro's image processing pipeline
// 3. Build-time image optimization

Markdown Image Syntax Support

The plugin supports various markdown image syntaxes:

Direct Images

![Alt text](image.png)
![Alt text](image.png "Title")

Image References

![Alt text][ref]
![Alt text][ref "Title"]

[ref]: image.png
[ref]: image.png "Title"

HTML Images (via remark-rehype)

<img src="image.png" alt="Alt text">

All formats are processed and their sources extracted for collection.

Performance Considerations

  • Lazy Evaluation: Images are collected during AST traversal
  • Deduplication: Uses Set to avoid duplicate entries
  • URL Validation: Efficient pattern matching for remote validation
  • Memory Efficient: Stores only paths, not image data

Error Handling

The plugin is designed to be fault-tolerant:

  • Invalid URLs: Silently skipped, no errors thrown
  • Missing References: Image references without definitions are ignored
  • Malformed Patterns: Invalid remote patterns are skipped
  • Network Issues: No network calls made during collection

This ensures the markdown processing pipeline continues even with problematic image references.

docs

frontmatter.md

index.md

markdown-processing.md

rehype-plugins.md

remark-plugins.md

syntax-highlighting.md

tile.json