README

Markdown Parser for PHP

A fast, simple, and straightforward Markdown to HTML converter for PHP.

🚀 Installation

composer require fastvolt/markdown

📦 Basic Usage

use FastVolt\Helper\Markdown;

$text = "## Hello, World";

// Initialize the parser
$markdown = new Markdown(); // or Markdown::new()

// set markdown content 
$markdown->setContent($text);

// compile and get as raw HTML
echo $markdown->getHtml();

Output:

<h2>Hello, World</h2>

📄 Convert Markdown File to Raw HTML

sample.md:

#### Heading 4
### Heading 3
## Heading 2
# Heading 1

- List 1
- List 2

> THIS IS A BLOCKQUOTE

[A LINK](https://github.com/fastvolt)

index.php:

$markdown = Markdown::new();

// add markdown file to parse 
$markdown->addFile(__DIR__ . '/sample.md');

// compile and get as raw html
echo $markdown->getHtml();

Output:

<h4>Heading 4</h4>
<h3>Heading 3</h3>
<h2>Heading 2</h2>
<h1>Heading 1</h1>
<ul>
  <li>List 1</li>
  <li>List 2</li>
</ul>
<blockquote><p>THIS IS A BLOCKQUOTE</p></blockquote>
<a href="https://github.com/fastvolt">A LINK</a>

📝 Convert Markdown File to An HTML File

blogPost.md:

Here is a Markdown File Waiting To Be Compiled To an HTML File

index.php:

$markdown = Markdown::new()
    // add markdown file
    ->addFile(__DIR__ . '/blogPost.md')

    // add output directory
    ->addOutputDirectory(__DIR__ . '/pages/')

    // compile as an html file
    ->saveToHtmlFile(filename: 'index.html');

if ($markdown) {
  echo "Compiled to ./pages/index.html";
}

Convert Directory to HTML Directory Structure

This compiles all .md files in a source directory into a mirrored structure of .html files in an output directory.

use FastVolt\Helper\Markdown;
use FastVolt\Helper\Markdown\Enums\MarkdownEnum;

$markdown = Markdown::new()
    // Set the source directory to read all .md files from (including sub-directories)
    ->setSourceDirectory(__DIR__ . '/docs/')
    
    // Set the output directory to compile the mirrored HTML structure to (Alias: ->setCompileDir())
    ->addOutputDirectory(__DIR__ . '/public/')
    
    // Run the directory conversion process
    ->run(MarkdownEnum::TO_HTML_DIRECTORY);

if ($markdown) {
    echo "Directory conversion successful!";
}

// If '/docs/guide/*.md' exists, it creates '/public/guide/*.html'.

Single Point Execution

This is the universal executor that can operate in three different modes using the MarkdownEnum enum and run method.

Interface

  run(
    MarkdownEnum $as, 
    ?string $fileName
  ): mixed;

MarkdownEnum Interface

enum MarkdownEnum 
{
  // convert markdown source to raw html (raw/file => raw html)
  case TO_HTML;

  // convert markdown source to an html file (markdown raw/file => html file)
  case TO_HTML_FILE;

  // convert markdown source directory to html directory (markdown directory => html directory)
  case TO_HTML_DIRECTORY;
}

Usage Examples

Using The MarkdownEnum::TO_HTML Enum

This is an alternative way to call getHtml().

Markdown::new()
    ->setContent('# Heading 1')
    ->run(MarkdownEnum::TO_HTML);

Using The MarkdownEnum::TO_HTML_FILE Enum

This is an alternative way to call saveToHtmlFile().

Markdown::new()
    ->addOutputDirectory(__DIR__ . '/build')
    ->run(MarkdownEnum::TO_HTML_FILE, 'index.html');

Using The MarkdownEnum::TO_HTML_DIRECTORY Enum

This is the only method that uses setSourceDirectory(). It crawls the source directory, converts all .md files, and saves them (preserving the folder structure) to the output directory.

Markdown::new()
    ->setSourceDirectory(__DIR__ . '/src/my-docs')
    ->addOutputDirectory(__DIR__ . '/public/docs')
    ->run(MarkdownEnum::TO_HTML_DIRECTORY);

🔒 Sanitizing HTML Output (XSS Protection)

You can sanitize input HTML and prevent cross-site scripting (XSS) attack using the sanitize flag.

$sanitize: Set to true (default) to escape HTML tags in the Markdown. Set to false only if you completely trust the source of your Markdown and need raw HTML to be rendered.

$markdown = Markdown::new(
  sanitize: true
);

$markdown_unsafe = Markdown::new(
  sanitize: false
);

$content = '<h1>Hello World</h1>';

echo $markdown
  ->setContent($content)
  ->getHtml();

echo $markdown_unsafe
  ->setContent($content)
  ->getHtml();

Output:

Sanitize Enabled: <p>&lt;h1&gt;Hello World&lt;/h1&gt;</p>

Sanitize Disabled: <h1>Hello World</h1>

⚙️ Advanced Use Case

Inline Markdown

$markdown = Markdown::new();

$markdown->setInlineContent('_My name is **vincent**, the co-author of this blog_');

echo $markdown->getHtml();

Output:

<i>My name is <strong>vincent</strong>, the co-author of this blog</i>

NOTE: Some markdown symbols are not supported with this method

Example #1

Combine multiple markdown files, contents and compile them in multiple directories:

Header.md

# Blog Title  
### Here is the Blog Sub-title

Footer.md

### Thanks for Visiting My BlogPage

index.php

$markdown = Markdown::new(sanitize: true)
    // include header file's markdown contents
    ->addFile('./Header.md')
    // body contents
    ->setInlineContent('_My name is **vincent**, the co-author of this blog_')
    ->setContent('Kindly follow me on my GitHub page via: [@vincent](https://github.com/oladoyinbov).')
    ->setContent('Here are the lists of my projects:')
    ->setContent('
- Dragon CMS
- Fastvolt Framework.
  + Fastvolt Router
  + Markdown Parser.
    ')
    // include footer file's markdown contents
    ->addFile(__DIR__ . '/Footer.md')
    
    // add the main compilation directory 
    ->addOutputDirectory(__DIR__ . '/pages/')
    
    // add another compilation directory to backup the result
    ->addOutputDirectory(__DIR__ . '/backup/pages/')

    // compile and store as 'index.html'
    ->saveToHtmlFile(file_name: 'index.html');

if ($markdown) {
  echo "Compile Successful. Files created in /pages/ and /backup/pages/";
}

Output: pages/index.html, backup/pages/index.html

<h1>Blog Title</h1>
<h3>Here is the Blog Sub-title</h3>
<i>My name is <strong>vincent</strong>, the co-author of this blog</i>
<p>Kindly follow me on my github page via: <a href="https://github.com/oladoyinbov">@vincent</a>.</p>
<p>Here are the lists of my projects:</p>
<ul>
  <li>Dragon CMS</li>
  <li>Fastvolt Framework.
    <ul>
      <li>Fastvolt Router</li>
      <li>Markdown Parser.</li>
    </ul>
  </li>
</ul>
<h3>Thanks for Visiting My BlogPage</h3>

Error Handling

The parser uses custom exceptions for clarity:

• MarkdownFileNotFound: Thrown when a file specified in addFile() or a directory in setSourceDirectory() does not exist.
• LogicException: Thrown if you try to execute a conversion (getHtml() or saveToHtmlFile()) before any content (setContent, addFile, etc.) has been added to the queue.
• RuntimeException: Thrown if the system fails to create an output directory (mkdir fails) or if a required directory is missing during run() execution.

🧠 Interface Method Reference

The parser uses a fluent (chainable) API. This is your command cheatsheet for configuration and execution:

Supported Formatting Symbols

✅ Requirements

PHP 8.1 or newer.

ℹ️ Notes

This library is an extended and simplified version of the excellent Parsedown by Erusev.

📄 License

This project is open-source and licensed under the MIT License by @fastvolt.