Download the PHP package cassarco/markdown-tools without Composer

markdown-tools

A Laravel package for processing markdown files with validation and custom handlers.

Why?

Markdown files with YAML front-matter are a great way to manage content. They're version-controlled, portable, and easy to edit. But when your Laravel application needs that content in the database, you need a reliable way to import it.

This package lets you:

• Sync markdown to your database - Import blog posts, documentation, or any content from markdown files to Eloquent models, keeping them in sync as you update your files.
• Validate front-matter - Use Laravel's validation rules to ensure every markdown file has the required metadata (title, slug, dates, etc.) before processing.
• Process multiple content types - Define separate schemes for different content types (articles, docs, pages) each with their own validation rules and handlers.
• Automate in CI/CD - Run the command in your deployment pipeline to automatically sync content changes.

How it works

Define one or more schemes in your configuration file, then run the bundled command to process them.

Installation

Install the package via composer:

Run the install command to publish the config and action stubs:

This publishes:

• config/markdown-tools.php - configuration file
• app/Actions/MarkdownFileHandler.php - handler for processing markdown files
• app/Actions/MarkdownFileRules.php - validation rules for front-matter

Alternatively, publish them separately:

Configuration

The published config file defines your schemes:

Usage

Define Validation Rules

Edit app/Actions/MarkdownFileRules.php to specify validation rules for front-matter properties:

Define a Handler

Edit app/Actions/MarkdownFileHandler.php to process each markdown file:

Process Your Schemes

Run the bundled command:

If files fail validation, you'll see Laravel validation errors:

MarkdownFile Methods

The handler receives a MarkdownFile instance with these methods:

Real-World Example

Here's how I use this package to sync markdown files to my database:

Upgrading from v1 to v2

Version 2.0 introduces breaking changes to support config caching. Handlers and rules are now class-based instead of closures.

Step 1: Update your dependencies

This requires Laravel 11+ and PHP 8.3+.

Step 2: Publish the action stubs

This creates app/Actions/MarkdownFileHandler.php and app/Actions/MarkdownFileRules.php.

Step 3: Migrate your handler logic

Move your closure logic from the config file to the new handler class.

Before (v1):

After (v2):

Step 4: Migrate your validation rules

Move your rules array to the new rules class.

Before (v1):

After (v2):

Step 5: Update your config

Replace closures with class references:

Note: The default scheme was renamed from 'markdown' to 'default'.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you find a bug that impacts the security of this package please send an email to [email protected] instead of using the issue tracker.

Credits

• Carl Cassar
• Cassar & Co
• All Contributors

License

The MIT License (MIT). Please see License File for more information.