alexoliverwd/m2s

A small package that provides a robust solution for, extracting metadata from Markdown files, and storing the data in an SQLite database

1.0.1 2026-01-21 19:55 UTC

Requires

• php: >=8.5
• spatie/yaml-front-matter: ^2.1

Requires (Dev)

• laravel/pint: ^1.27
• pestphp/pest: ^4.3
• phpstan/phpstan: ^2.1

MIT

• Alex Oliver

• markdown
• sqlite

README

The Markdown to SQLite package provides a robust solution for parsing Markdown files, extracting metadata, and storing the data in an SQLite database. This documentation highlights the main classes and their functionality.

Main Classes

1. Parser Class

The Parser class orchestrates the process of reading Markdown files, creating Document objects, and storing them in the database.

Key Features:

• Source Folder Validation: Ensures the source folder exists and contains Markdown files.
• Database Validation: Ensures the target database file has a valid extension.
• Batch Processing: Iterates through Markdown files in the source folder and updates the database.

Example Usage:

use AOWD\MarkdownToSQLite\Parser;

$parser = new Parser(
    source_folder: '/path/to/markdown/files',
    target_database: '/path/to/database.sqlite',
    omit_path_from_slug: '/path/to'
);

$parser->update(); // Adds or updates records in the database
$parser->cleanSlate(); // Clears the database and reprocesses all files

Error Handling:

• Throws SourceIsNotDirectory if the source folder does not exist.
• Throws FileExtension if the target database file has an invalid extension.
• Throws TargetIsDirectory if the target database path is a directory.

Workflow Overview

1. Initialise the Parser:

   • Provide the source folder containing Markdown files and the target SQLite database file.
   • Optionally, specify a path to omit from slugs.

2. Process Files:

   • Use the update() method to parse Markdown files and store their data in the database.
   • Use the cleanSlate() method to clear the database and reprocess all files.

3. Manage Records:

   • Use the Model class to add, replace, or clear records.
   • Retrieve the total record count or specific documents as needed.

Example Workflow

use AOWD\MarkdownToSQLite\Parser;

$parser = new Parser(
    source_folder: '/path/to/markdown/files',
    target_database: '/path/to/database.sqlite',
    omit_path_from_slug: '/path/to'
);

// Process Markdown files and store data in the database
$parser->update();

// Clear the database and reprocess all files
$parser->cleanSlate();

2. Document Class

The Document class is responsible for handling individual Markdown files. It parses the file, extracts metadata, and prepares the content for database storage.

Key Features:

• Slug Generation: Creates a unique slug for the document.
• Frontmatter Parsing: Extracts and validates frontmatter as JSON.
• Content Hashing: Computes a SHA-256 hash for the document.
• Body Extraction: Extracts the main content of the Markdown file.

Example Usage:

use AOWD\MarkdownToSQLite\Document;

$document = new Document('/path/to/file.md');
$document->omitPathFromSlug('/path/to');
echo $document->slug; // Outputs the formatted slug

Error Handling:

• Throws Exception if the file does not exist.
• Throws FileExtension if the file is not a Markdown file.

3. Model Class

The Model class manages the SQLite database, including creating tables, adding records, and clearing data.

Key Features:

• Database Initialisation: Creates the database and the documents table if they do not exist.
• Transaction Management: Supports transactions for batch operations.
• Record Management:
  • Add or replace documents in the database.
  • Clear all records from the database.
  • Retrieve the total record count.

Error Handling:

• Ensures the database is properly initialised before operations.