Module markdown 

Markdown file operations and metadata extraction for Claude Code resources.

This module provides comprehensive support for reading, writing, and manipulating Markdown files that contain Claude Code agents and snippets. It handles both plain Markdown files and files with structured metadata in frontmatter.

Overview

The markdown module is a core component of AGPM that:

• Parses Markdown files with optional YAML or TOML frontmatter
• Extracts structured metadata for dependency resolution
• Preserves document structure during read/write operations
• Provides utilities for file discovery and validation
• Supports atomic file operations for safe installation
• Extracts and validates file references within markdown content

Supported File Formats

Plain Markdown Files

Standard Markdown files without frontmatter are fully supported:

# Python Code Reviewer

This agent specializes in reviewing Python code for:
- PEP 8 compliance
- Security vulnerabilities
- Performance optimizations

## Usage

When reviewing code, I will...

YAML Frontmatter Format

Files can include YAML frontmatter for structured metadata:

---
title: "Python Code Reviewer"
description: "Specialized agent for Python code quality review"
version: "2.1.0"
author: "Claude Code Team"
type: "agent"
tags:
  - "python"
  - "code-review"
  - "quality"
dependencies:
  agents:
    - path: agents/syntax-checker.md
  snippets:
    - path: snippets/security-scanner.md
---

# Python Code Reviewer

This agent specializes in reviewing Python code...

TOML Frontmatter Format

TOML frontmatter is also supported using +++ delimiters:

+++
title = "JavaScript Snippet Collection"
description = "Useful JavaScript utilities and helpers"
version = "1.0.0"
author = "Community Contributors"
type = "snippet"
tags = ["javascript", "utilities", "helpers"]
+++

# JavaScript Snippet Collection

## Array Utilities

```javascript
function unique(arr) {
    return [...new Set(arr)];
}

Metadata Schema

The frontmatter metadata follows this schema:

Field	Type	Description	Required
title	string	Human-readable resource title	No
description	string	Brief description of the resource	No
version	string	Resource version (semver recommended)	No
author	string	Author name or organization	No
type	string	Resource type (“agent” or “snippet”)	No
tags	array	Tags for categorization	No
dependencies	object	Structured dependencies by resource type	No

Additional custom fields are preserved in the extra map.

Content Extraction

When metadata is not explicitly provided in frontmatter, the module can extract information from the Markdown content:

• Title: Extracted from the first level-1 heading in the content
• Description: Extracted from the first paragraph after headings

This allows resources to work without frontmatter while still providing useful metadata for dependency resolution and display.

File Operations

All file operations are designed to be safe and atomic:

• Parent directories are created automatically during writes
• Content is validated during parsing to catch errors early
• File extensions are validated (.md, .markdown)
• Recursive directory traversal for bulk operations

Usage Examples

Basic Reading and Writing

use agpm_cli::markdown::MarkdownDocument;
use std::path::Path;

// Read a markdown file
let doc = MarkdownDocument::read(Path::new("agents/reviewer.md"))?;

// Access metadata
if let Some(metadata) = &doc.metadata {
    println!("Title: {:?}", metadata.title);
    println!("Version: {:?}", metadata.version);
    println!("Tags: {:?}", metadata.tags);
}

// Extract title from content if not in metadata
if let Some(title) = doc.get_title() {
    println!("Extracted title: {}", title);
}

// Write to a new location
doc.write(Path::new("installed/reviewer.md"))?;

Creating Documents Programmatically

use agpm_cli::markdown::{MarkdownDocument, MarkdownMetadata};

// Create metadata
let mut metadata = MarkdownMetadata::default();
metadata.title = Some("Custom Agent".to_string());
metadata.version = Some("1.0.0".to_string());
metadata.tags = vec!["custom".to_string(), "utility".to_string()];

// Create document with metadata
let content = "# Custom Agent\n\nThis is a custom agent...";
let doc = MarkdownDocument::with_metadata(metadata, content.to_string());

// The raw field contains formatted frontmatter + content
println!("{}", doc.raw);

Batch File Processing

use agpm_cli::markdown::{list_markdown_files, MarkdownDocument};
use std::path::Path;

// Find all markdown files in a directory
let files = list_markdown_files(Path::new("resources/"))?;

for file in files {
    let doc = MarkdownDocument::read(&file)?;
     
    if let Some(title) = doc.get_title() {
        println!("{}: {}", file.display(), title);
    }
}

Integration with AGPM

This module integrates with other AGPM components:

• crate::manifest: Uses metadata for dependency resolution
• crate::lockfile: Stores checksums and installation paths
• crate::source: Handles remote resource fetching
• crate::core: Provides core types and error handling

See the respective module documentation for integration details.

Modules

frontmatter

Frontmatter parsing with grey_matter Engine trait and Tera templating.

reference_extractor

File reference extraction and validation for markdown documents.

Structs

MarkdownDocument

A parsed Markdown document representing a Claude Code resource.

MarkdownMetadata

Structured metadata extracted from Markdown frontmatter.

Functions

is_markdown_file

Check if a path represents a Markdown file based on its extension.

list_markdown_files

Recursively find all Markdown files in a directory.

Type Aliases

MarkdownFile

Type alias for MarkdownDocument for backward compatibility.