https://github.com/fastvolt/markdown
A Fast, Simple and Straight-forward Markdown Parser and Markdown to HTML Converter for PHP.
https://github.com/fastvolt/markdown
markdown markdown-converter markdown-it markdown-parser markdown-to-html php php-markdown php-markdown-parser
Last synced: 24 days ago
JSON representation
A Fast, Simple and Straight-forward Markdown Parser and Markdown to HTML Converter for PHP.
- Host: GitHub
- URL: https://github.com/fastvolt/markdown
- Owner: fastvolt
- Created: 2023-11-06T18:54:08.000Z (over 2 years ago)
- Default Branch: v0.3.0
- Last Pushed: 2025-11-12T00:00:44.000Z (5 months ago)
- Last Synced: 2025-11-12T00:18:52.871Z (5 months ago)
- Topics: markdown, markdown-converter, markdown-it, markdown-parser, markdown-to-html, php, php-markdown, php-markdown-parser
- Language: PHP
- Homepage:
- Size: 143 KB
- Stars: 44
- Watchers: 0
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Markdown Parser for PHP
A fast, simple, and straightforward Markdown to HTML converter for PHP.
## 🚀 Installation
```sh
composer require fastvolt/markdown
```
## 📦 Basic Usage
```php
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:
```html
Hello, World
```
## 📄 Convert Markdown File to Raw HTML
> ***sample.md:***
```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:***
```php
$markdown = Markdown::new();
// add markdown file to parse
$markdown->addFile(__DIR__ . '/sample.md');
// compile and get as raw html
echo $markdown->getHtml();
```
> ***Output:***
```html
Heading 4
Heading 3
Heading 2
Heading 1
- List 1
- List 2
THIS IS A BLOCKQUOTE
A LINK
```
## 📝 Convert Markdown File to An HTML File
> ***blogPost.md:***
```md
Here is a Markdown File Waiting To Be Compiled To an HTML File
```
> ***index.php:***
```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.
```php
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
```php
run(
MarkdownEnum $as,
?string $fileName
): mixed;
```
### MarkdownEnum Interface
```php
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()`.
```php
Markdown::new()
->setContent('# Heading 1')
->run(MarkdownEnum::TO_HTML);
```
#### Using The `MarkdownEnum::TO_HTML_FILE` Enum
> This is an alternative way to call `saveToHtmlFile()`.
```php
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.
```php
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.
```php
$markdown = Markdown::new(
sanitize: true
);
$markdown_unsafe = Markdown::new(
sanitize: false
);
$content = '
Hello World
';echo $markdown
->setContent($content)
->getHtml();
echo $markdown_unsafe
->setContent($content)
->getHtml();
```
> ***Output:***
```html
Sanitize Enabled:
<h1>Hello World</h1>
Sanitize Disabled:
Hello World
```
## ⚙️ Advanced Use Case
### Inline Markdown
```php
$markdown = Markdown::new();
$markdown->setInlineContent('_My name is **vincent**, the co-author of this blog_');
echo $markdown->getHtml();
```
> ***Output:***
```html
My name is vincent, the co-author of this blog
```
> ***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***
```md
# Blog Title
### Here is the Blog Sub-title
```
> ***Footer.md***
```md
### Thanks for Visiting My BlogPage
```
> ***index.php***
```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`
```html
Blog Title
Here is the Blog Sub-title
My name is vincent, the co-author of this blog
Kindly follow me on my github page via: @vincent.
Here are the lists of my projects:
- Dragon CMS
- Fastvolt Framework.
- Fastvolt Router
- Markdown Parser.
Thanks for Visiting My BlogPage
```
## 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:
| Method Name | Return Type | Description |
| :--- | :--- | :--- |
| `::new(bool $sanitize = true)` | `self` | **Initialize** the parser instance. The preferred static factory method. |
| `->setSourceDirectory(string $name)` | `static` | Sets the **input root directory** for whole-directory compilation. |
| `->setContent(string $content)` | `static` | Adds **multi-line** Markdown content (supports lists, headings, etc.) to the queue. |
| `->setInlineContent(string $content)` | `static` | Adds **single-line** Markdown content (*bold*, **italic**) to the queue. |
| `->addFile(string $fileName)` | `static` | Adds a single Markdown file path to the compilation queue. *(Alias: `->setFile()`)* |
| `->addMultipleFiles(array $names)` | `static` | Adds an array of Markdown file paths to the compilation queue. |
| `->addOutputDirectory(string $dir)` | `static` | Adds a directory where the compiled HTML will be saved. Allows multiple targets. *(Alias: `->setCompileDir()`)* |
| `->addMultipleOutputDirectories(array $dirs)` | `static` | Adds an array of directories where the compiled HTML will be saved. |
| `->getHtml()` | `string\|null` | **Execute** compilation and return the raw HTML string. *(Alias: `->toHtml()`)* |
| `->saveToHtmlFile(string $name)` | `bool` | **Execute** compilation and write the output to the specified HTML file(s). *(Alias: `->toHtmlFile()`)* |
| `->run(MarkdownEnum $as, ?string $file)` | `mixed` | Universal command to execute conversion based on the specified `MarkdownEnum` target. |
## Supported Formatting Symbols
| Markdown Syntax | Description | Example Syntax | Rendered Output |
|-----------------------------|-----------------------------|-------------------------------------------|----------------------------------------|
| `#` to `######` | Headings (H1–H6) | `## Heading 2` |
Heading 2
|| `**text**` or `__text__` | Bold | `**bold**` | bold |
| `*text*` or `_text_` | Italic | `*italic*` | italic |
| `~~text~~` | Strikethrough | `~~strike~~` |
| `` `code` `` | Inline code | `` `echo` `` |
echo |
|
```
code block
``` | Code block | ```` ```php\n echo "Hi"; \n``` ```` | `...| `-`, `+`, or `*` | Unordered list | `- Item 1`
`* Item 2` | `
- Item
| `1.` `2.` | Ordered list | `1. Item`
`2. Item` | `
- Item
| `[text](url)` | Hyperlink | `[GitHub](https://github.com)` | GitHub |
| `> blockquote` | Blockquote | `> This is a quote` |
This is a quote|
| `---`, `***`, `___` | Horizontal Rule | `---` | `
` |
| `` | Image | `` | `
` |
| `\` | Escape special character | `\*not italic\*` | *not italic* (as text) |
## ✅ Requirements
PHP 8.1 or newer.
## ℹ️ Notes
> This library is an extended and simplified version of the excellent [Parsedown](https://github.com/erusev/parsedown/) by Erusev.
## 📄 License
This project is open-source and licensed under the MIT License by @fastvolt.